API cookbook

This cookbook gives short, composable examples for common Sume API workflows. For exact fields and enums, use the API reference and /api/openapi.json.

Setup

Check that the key works:

Check available credits before starting paid work:

Create and poll a video job

Create the job:

The response includes job_id.

Poll status:

Fetch the result:

Create an image from Brand references

Read the current Brand DNA profile:

If the response includes images[].reference_url, pass selected references to image generation:

Only use reference URLs that Sume returned to your workspace. Do not paste private or signed URLs into logs.

Upload a video to Asset Library

Request an upload target:

Upload the file bytes to the returned upload_url using the returned required_headers. Do not include the Sume API Authorization header in the storage PUT request.

Finalize the uploaded asset:

The asset upload enters processing. Use Asset Library search after ingest completes.

Scene assets may include a scene-level media_url, thumbnail_url, source_video, scene metadata, and search context. Prefer scene-level media when present; fall back to source video plus timecodes only when your workflow supports trimming.

Prepare a Face Swap source video

Face Swap requires an uploaded Sume media URL with purpose face_swap_source_video.

After uploading bytes to the returned upload URL, create Face Swap jobs:

Poll each returned job id with GET /jobs/{jobId}.

Analyze a public reference

Reference Analysis accepts public TikTok or Instagram Reel URLs.

The response includes required_credits and job_id. Poll the job and fetch the final result through the jobs endpoints.

Handle failures safely

For failed API requests, preserve the request id:

For failed jobs, preserve the job id, status, and sanitized error code/message. Do not log API keys, signed URLs, storage object keys, raw provider payloads, private media URLs, user emails, or workspace/user ids.