Developers
Building on the Sume API: keys and hosts, jobs and runs, polling, webhooks, idempotency, errors and rate limits, the SDK, the CLI, and MCP auth.
Decart lucy-latest vs a pinned Lucy model; Sume catalog ids
Decart's lucy-latest alias can move while legacy Lucy Clip costs $0.15 per second against $0.04 for Lucy 2.5. Why pin a model id, and how to do it on Sume.
GPT Image 2.5 edit changed shape? Use aspect_ratio auto on Sume
On Sume edit and image-to-image calls, aspect_ratio auto is not the same as leaving the field out. How to read the model descriptor and keep the photo's shape.
GPT Image 2.5 edit with several references: number each image
With up to 16 references in a GPT Image 2.5 edit, name each one by number and role in the prompt. A Sume request with three references, and what to check.
H3 Max Recast in Python: submit, poll and read the result
A Python script for Sume's h3-max-recast: submit with an Idempotency-Key, poll until the job is terminal, read the result. Cost per clip included.
H3 Max Recast request rejected: every field Sume refuses
Sume refuses H3 Max Recast bodies with aspect_ratio, generate_audio, bitrate_mode, frame or audio references, or a duration outside 5-30 s. The full list.
Sume job error category quota or queue vs 402 and 429
A Sume job error category quota means add funds or lower cost; queue means retry with the same key. They sit on the job, apart from 402 and 429 at submit.
Sume job failed with worker_timeout: poll again or retry?
A Sume job error in the worker_timeout or generation_timeout category means poll status or retry later. runtime_unavailable means retry later, gently.
jobs_result with job_ids: read ok per entry, re-read failed_job_ids
A Sume MCP jobs_result batch returns ok plus value or error per id. One job_not_completed does not fail the rest; re-read partial_failure.failed_job_ids.
jobs_wait include_results: skip the second read, handle omitted ids
Set include_results true on Sume MCP jobs_wait: completed ids return jobs_result in results[]; ids that do not fit are named in results_omitted.job_ids.
jobs_wait returned operator_stopped: what it means and what to do
operator_stopped on Sume jobs_wait: operations stopped the job. It is terminal, has no output, and its hold was refunded. Wait only on the pending ids.
jobs_wait timeout_seconds 600 returns at 55 seconds, clamped
Sume MCP jobs_wait accepts timeout_seconds up to 600 but clamps it to 55 and says so in wait_slice_clamped. Repeat the wait instead.
jobs_wait fails on one unknown job id: why and how to avoid it
On Sume MCP, one unknown or foreign-workspace id fails the whole jobs_wait call. Store ids at submit time and wait only on ids from your own workspace.
NEXT_PUBLIC_ plus a Sume API key: why it ships to the browser
A NEXT_PUBLIC_ prefix inlines the value into client JavaScript at build time. Keep the Sume API key server-side, proxy via a route handler, rotate if it leaked.
Python preflight for a YouTube Short: length and shape check
A short Python script that reads Sume's video inspect probe and flags a clip over 180 seconds or not square or vertical, including 90 degree rotation.
Verify a Sume webhook in Rails: raw_post, skip_forgery_protection
A Rails controller that verifies Sume's sume-v1 HMAC over the raw body, accepts the rotation header, refuses an empty secret and skips CSRF for that route only.
script_run budgets: call, paid-call and timeout limits on MCP
script_run caps a Sume MCP program by timeout (5-55 s), max_calls and max_paid_calls, and stops with a named error code. Defaults, ceilings and what to do next.
Seedance "accepts at most 12 input_references": mixes that fit
Sume returns unsupported_capability when images + videos + audio on a Seedance request exceed 12. Which mixes pass, what fal limits per type, and how to trim.
One image to Seedance: reference, or first frame?
On Sume a single reference image with no frame field is priced and routed as reference-to-video; add a first frame to get image-to-video. How to choose.
Sume 503: provider_capacity_exceeded vs provider_not_configured
Sume 503s differ: provider_capacity_exceeded: retry later, same key; provider_not_configured is no hard retries, job_ledger_not_configured is an outage
SUME_CONFIG_DIR in GitHub Actions: keep Sume CLI config off the runner
Set SUME_API_KEY from a GitHub secret and SUME_CONFIG_DIR to a temp folder so the Sume CLI keeps its config off ~/.sume-com/config.json on a shared runner.
Image reference URL rejected on Sume: localhost, http, private hosts
Sume's Image API rejects localhost, private-network and non-HTTPS reference URLs before submission. A pre-flight check in Python and what to host instead.
Submit a Sume video job with curl, save it with sume jobs download
The CLI has no video generate command, but jobs watch and jobs download work on jobs created through the API. A shell script that submits, waits and saves.
Sume media tools: which answer 200 and which answer 202 by default
video-inspect defaults to sync, trim, filter, compose and detach to async, and video-frames always returns 202. Defaults, the 30 s wait, and how to poll each.
Sume queue capacity: max(3, concurrency x 5), and 7 jobs on Free
Sume's default queue capacity is max(3, concurrency_limit x 5). On Free that is 5 queued plus 1 processing, so a seventh live generation job gets queue_full.
Does the Sume SDK retry POSTs? Only with an Idempotency-Key
createSumeClient retries 408, 429 and 5xx twice with backoff, but replays a POST only when it carries an Idempotency-Key. How to set it and tune maxRetries.
Check an Avatar payload with sume tools schema before --confirm-paid
sume tools schema avatar-videos.create --json prints the exact fields before you pass --confirm-paid. A read-only pre-flight loop for a spending CLI command.
Timeline 1.0 warnings after stitching shots: which need a fix
Timeline 1.0 returns soft warnings, not failures. A list of the codes you will see on a stitched AI film, what each means, and which ones are worth acting on.
Did the edit stay in its region? A pixel-diff check for GPT Image 2.5
After a GPT Image 2.5 edit, measure how much changed outside the area you meant to change. A Pillow script that diffs the result against the original.
low_confidence_long_video: why video_frames warns past 90 seconds
Sume's video_frames returns the low_confidence_long_video warning when the source runs over 90 s. The job still succeeds; the hard cap is 300 s. What to do.
Check has_audio first: video_inspect frames false before STT or detach
A free probe-only video_inspect tells you probe.has_audio before you reserve STT or run audio detach, so silent clips never hit the no-audio errors.
video_inspect silence_split_seconds: sentence segments for captions
How silence_split_seconds (0.2 to 3) shapes Sume video-inspect sentence segments, the 0.5 s default in the repo, and turning segments into caption cues.
Sume video tools: public URL or media import first? Per tool
Video captions takes a public HTTPS URL; trim, filter, inspect, frames, compose and detach need a workspace media.sume.com clip. A tool-by-tool input guide.
Avatar catalog search returns few results: auto_expand explained
When an avatar catalog search is thin, Sume relaxes filters in a set order and lists them in relaxed_filters. Set auto_expand to false for strict matching.
Approved an avatar preview, now the hook changed: new preview
Sume's generate-video from an avatar preview keeps the script and first frame. Only quality can change, so a new hook needs a new preview.
Avatar video: avatar_handle or avatar_id per scene?
Sume avatar video launch requests use avatar_handle. Per scene, a character object takes avatar_id or avatar_handle, but only one avatar is allowed per video.
Avatar video_inputs limits: 20 scenes, 2,000 characters each
Sume's avatar video video_inputs accepts 1 to 20 scenes, each text scene up to 2,000 characters and 60 seconds, inside the 4-60 second total window.
Claude structured outputs drop minimum and maxLength; Sume keeps them
Anthropic lists minimum, maxLength and recursion as unsupported in structured outputs. Sume's output_schema accepts the first two; here is what differs.
curl --retry on a POST: retry a Sume submit with one key
curl --retry also retries a POST, and it resends the same headers each time. Put an Idempotency-Key on a Sume submit first, then pick --retry-max-time.
Dub a 20-minute video: audio detach 900 s cap, STT 600 s, TTS 1,200 s
A 20-minute video needs chunking before a dub: audio detach outputs at most 900 s, STT reservation tops out at 600 s, and TTS fails past 1,200 s.
FLUX API 402, 403 and 503 errors, and Sume's equivalents
BFL returns 402 for credits, 403 for key permission, 503 for load. Sume returns 402 insufficient_credits and 503 provider_capacity_exceeded. What to do.
Gemini prefixItems tuple schema: Sume rejects it, use an object
Gemini lists prefixItems for tuple-like arrays. Sume's output_schema allowlist omits it and returns unsupported_keyword; model each slot as a named property.
Gemini recursive schema with $ref "#": what Sume accepts instead
Gemini's docs show an org-chart schema that recurses with $ref "#". Sume rejects that root reference; recurse through a named $defs entry instead.
MiniMax H3 Max lip sync audio_url: Sume media host only
Sume's MiniMax H3 Max Lip Sync takes a public HTTPS audio_url on the Sume media host, 5 to 14.8 seconds, max 10 MB. Other hosts are rejected.
MiniMax H3 Max lip sync: 1080p max, no 2K, speed_tier ignored
Sume's MiniMax H3 Max Lip Sync offers 480p, 768p (default) and 1080p; 2K is not offered, and speed_tier is accepted but ignored.
MiniMax H3 Max lip sync image aspect ratio: 0.4 to 2.5
The still for Sume's MiniMax H3 Max Lip Sync must have an aspect ratio between 0.4 and 2.5. That covers 9:16 through 21:9 if ratio means width over height.
Sume job metadata on Kling motion control and H3 Max lip sync
Both Kling 3.0 Motion Control and MiniMax H3 Max Lip Sync accept a metadata object stored with the Sume job request. It is not sent to the provider.
Kling motion control with avatar_id instead of image_url
Sume's Kling 3.0 Motion Control takes image_url or avatar_id/avatar_handle, never both. A ready avatar resolves server-side to its identity still.
Kling motion control sync mode: a 30-second wait, then poll
Sume's sync and subscribe modes on Kling 3.0 Motion Control wait at most 30 seconds. A clip usually outlasts that, so poll status_url; do not resubmit.