PricingAPI keys
  • Overview
  • Quickstart
  • Authentication
  • API reference
  • Recipes

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

bash
curl https://api.sume.com/v1/me \
  -H "Authorization: Bearer $SUME_API_KEY"

List current capabilities

bash
curl https://api.sume.com/v1/catalog \
  -H "Authorization: Bearer $SUME_API_KEY"

Create an avatar

curl -sS -X POST "https://api.dev.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-60 seconds inclusive. For the default plus path, do not send quality.

curl -sS -X POST "https://api.dev.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.dev.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.dev.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.dev.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.dev.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.dev.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.dev.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.dev.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.dev.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

bash
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

bash
curl https://api.sume.com/v1/balance \
  -H "Authorization: Bearer $SUME_API_KEY"

curl https://api.sume.com/v1/usage \
  -H "Authorization: Bearer $SUME_API_KEY"

On this page

  • Verify a key
  • List current capabilities
  • Create an avatar
  • Create an avatar video
  • Preview first frames, then generate
  • Face swap (Beta)
  • Caption an existing video
  • Search trending TikTok videos
  • Generate an image
  • Generate a video
  • Generate music
  • Poll and fetch result
  • Use media inputs
  • Read usage