API reference
Recipes
Short current-platform recipes for common Sume API workflows.
This page is a short index of recipes. For Avatar, the canonical
/v1/avatar-1.0/* routes are the best choice. The deep guides are in
Models.
A Format that you run for your own customers has a longer recipe of its own. Refer to Embed a Format in your product.
Verify a key
A 200 means the key works. It reads the balance the key spends, in US
dollars, and spends nothing:
curl https://api.sume.com/v1/open/balance \
-H "Authorization: Bearer $SUME_API_KEY"A key from Dashboard → API keys does not call GET /v1/me: that answers
403 open_key_route_not_allowed.
List current capabilities
curl https://api.sume.com/v1/catalog \
-H "Authorization: Bearer $SUME_API_KEY"Create an avatar
curl -sS -X POST "https://api.sume.com/v1/avatar-1.0/generate" \
-H "Authorization: Bearer $SUME_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"avatar_handle":"studio_presenter","input":{"type":"prompt","prompt":"A friendly studio presenter in neutral lighting"}}'Create an avatar video
The estimated length of an avatar-video script must be 4-12 seconds
inclusive. For the default plus path, do not send quality.
curl -sS -X POST "https://api.sume.com/v1/avatar-1.0/talking-video" \
-H "Authorization: Bearer $SUME_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"avatar_handle":"sume_clawra","script":"Say hello to the Sume developer platform.","product_image":"https://example.com/product.png","scene":{"type":"prompt","prompt":"Bright studio with clean product table"},"quality":"plus","resolution":"720p","aspect_ratio":"9:16"}'Preview first frames, then generate
curl -sS -X POST "https://api.sume.com/v1/avatar-video-previews" \
-H "Authorization: Bearer $SUME_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"avatar_handle":"sume_clawra","script":"Share a quick product benefit in one concise sentence.","scene":{"type":"prompt","prompt":"Bright product demo set"},"quality":"plus","aspect_ratio":"9:16","captions":{"enabled":true,"style":"slam"}}'After the preview job completes:
curl -sS -X POST "https://api.sume.com/v1/avatar-video-previews/avp_123/generate-video" \
-H "Authorization: Bearer $SUME_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"quality":"standard"}'Face swap (Beta)
curl -sS -X POST "https://api.sume.com/v1/models/sume/avatar-face-swap/v1.0/runs" \
-H "Authorization: Bearer $SUME_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"avatar_handle":"sume_clawra","video_url":"https://example.com/inputs/source-video.mp4","quality":"plus","mode":"async"}'Caption an existing video
curl -sS -X POST "https://api.sume.com/v1/video-captions" \
-H "Authorization: Bearer $SUME_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"video_url":"https://example.com/inputs/talking-clip.mp4","style":"slam","language":"auto"}'Search trending TikTok videos
curl -sS -X POST "https://api.sume.com/v1/trending-videos/search" \
-H "Authorization: Bearer $SUME_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"query":"project management","platform":"tiktok","window":"this-week","limit":20,"summary_mode":"metadata"}'Generate an image
Deep guide: Image 1.0.
curl -sS -X POST "https://api.sume.com/v1/image-1.0/generate" \
-H "Authorization: Bearer $SUME_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"prompt":"Product hero shot of a matte black water bottle on marble","aspect_ratio":"1:1","quality":"high","num_images":1,"output_format":"png"}'Generate a video
Deep guide: Video 1.0.
curl -sS -X POST "https://api.sume.com/v1/video-1.0/generate" \
-H "Authorization: Bearer $SUME_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"prompt":"Slow push-in on a ceramic mug steam rising in soft morning light","aspect_ratio":"9:16","resolution":"720p","duration":5,"generate_audio":true,"routing_preset":"quality"}'Generate music
Deep guide: Music 1.0. Do not send duration on Music 1.0.
curl -sS -X POST "https://api.sume.com/v1/music-1.0/generate" \
-H "Authorization: Bearer $SUME_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"prompt":"Upbeat lo-fi beat with soft vinyl crackle, no vocals, no spoken word"}'Poll and fetch result
curl https://api.sume.com/v1/jobs/job_123/status \
-H "Authorization: Bearer $SUME_API_KEY"
curl https://api.sume.com/v1/jobs/job_123/result \
-H "Authorization: Bearer $SUME_API_KEY"Use media inputs
The API is URL-first. For normal flows, a separate asset upload is not necessary. Use public HTTPS URLs directly in these launch request fields:
- Avatar photo input:
input.image_url - Avatar Video product reference:
product_image - Avatar Video scene photo reference:
scene.image_url - Face swap / captions source:
video_url
Refer to Media inputs.
Read usage
The balance the key spends, in US dollars, and what it spent this month:
curl https://api.sume.com/v1/open/balance \
-H "Authorization: Bearer $SUME_API_KEY"Spend by day and by model, transactions, receipts and top-ups are in the
dashboard, under Settings → Usage and Settings → Billing. A key from
Dashboard → API keys gets 501 billing_in_dashboard from GET /v1/open/usage,
and 403 open_key_route_not_allowed from GET /v1/balance and
GET /v1/usage.