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.
Service-account 402: daily, monthly or per-end-user spend cap hit
Three different 402 codes mean three different caps. Read details.cap_usd_micros and current_usd_micros to see which window blocked the request.
spend_approval_queue_full 429: clear pending approvals, do not retry
A thread with too many pending spend approvals gets 429 spend_approval_queue_full. Resolve the pending ones first; a 503 store_misconfigured is for support.
spend_confirmation_required 402 on Sume: why retrying will not help
A 402 spend_confirmation_required means a person must approve the spend first. It is not a balance error: retryable is false and next_action is fix_input.
STT words into caption words: rename word to text, stay under 60 s
Sume STT returns words as {word, start, end}; the caption job wants {text, start, end}, end above start, 60 s or less, 1200 words at most. Map and filter.
Map the Sume error envelope to RFC 9457 problem details in 15 lines
RFC 9457 defines type, status, title, detail and instance. Sume's error.code, message and request_id map onto them; keep the retry fields as extensions.
Sume MCP assets_create vs upload: registered URLs are unverified
On Sume MCP, assets_create registers unverified metadata for a remote URL. For bytes you own, use assets_upload_url, a client PUT, then assets_complete.
Sume MCP conflicting_model: top-level model vs payload.model
avatar-image-to-video_create lifts payload.model to the top level. If the two differ you get conflicting_model plus supported_models. Send one, or match them.
Sume MCP dry run: next_step is only dry_run false, merge your payload
A paid Sume MCP dry run returns would_submit false and next_step arguments of just dry_run false. Re-send your original idempotency_key and payload with it.
Sume MCP generation_admission_rejected: read the preview first
generation_admission_rejected means the admission preview would not accept the request. Read the preview, then change the request or wait before retrying.
Sume job_failed_terminal: retryable true means reuse the same key
On job_failed_terminal never resubmit the identical payload. If error.retryable is true, re-issue the create with the same idempotency_key; else fix the input.
max_spend_usd on Sume MCP: floors to micros, missing estimate fails
max_spend_usd takes 0 to 10,000, floors to micros, and runs on the preview before dry_run returns. No usable estimate means missing_usage_estimate, not a pass.
Avatar preview failed on Sume MCP: stop_and_ask, do not generate video
When an avatar video preview fails or is canceled, Sume MCP returns recovery code stop_and_ask: do not call generate_video, report the reason, offer a rewrite.
timeline_get 409 job_not_completed on Sume MCP: retry, do not give up
A 409 job_not_completed from timeline_get means the render is still running, so retry. Call jobs_wait on the same job_id; never report the run blocked.
Sume MCP tools_schema safety object: build a tool allowlist from it
Sume's tools_schema returns a safety object per tool: paid_generation, read_only, requires_idempotency_key and more. Build your agent allowlist from it.
Sume queue position and ETA: none exists, poll generation_limits
Sume shows queue counts and remaining capacity, not a per-job position or ETA. Read generation_limits and keep new work inside the headroom formula.
Sume STT silence split: it only runs after the last sentence end
Sume STT cuts at terminal punctuation first; the 0.5 s silence rule only splits the unpunctuated run after the last terminal, not earlier pauses.
Translate a pack into 8 languages in parallel: queue limits by plan
Eight Ideogram 4.5 edits fit the Pro queue (24 accepted jobs) but not Free (6), so 2 get 429 queue_full. Python thread pool with retry; cost is $0.60 at medium.
Korean TTS segment text has no spaces, unless a digit is in it
Sume's TTS segment text joins tokens with spaces only if one has a Latin letter or digit; else with nothing. Use segments for timing, your script for text.
Pipes and @{} markers in a Sume TTS transcript: stripped, never spoken
Sume strips || cue breaks, @{...} markers and the display side of <display|spoken> before the voice reads; an empty result returns 400 transcript_no_speech.
usage_reservation_unavailable: a Sume job failed before it started
The usage reservation could not be placed, so Sume failed the queued job and gave back any hold. Nothing ran. Resubmit with the same Idempotency-Key.
'Use either first/end frame fields or reference_*_urls, not both'
A first frame pins the opening shot; references only guide it. Video Router refuses to mix them, so pick one mode per job and chain jobs if you need both.
What ends a Sume STT sentence segment: . ! ? and the Japanese marks
Sume ends a segment on . ! ? 。 ！ ？ … plus optional trailing quotes or closing parentheses; the corner bracket 」 and a fullwidth ） are not on that list.
Why Sume MCP results show [redacted]: the redaction field list
Sume MCP omits api_key fields and masks secrets and signed URLs as [redacted] in tool results. That is intended, not a failed call.
Bulk ad queue says completed: read counts.failed before you ship
A Sume bulk queue is completed when every item is terminal, not when every ad worked. A Python poller that backs off, then lists failed and canceled items.
Bulk queue replay returns 202 and the old queue: derive the key
A repeated Idempotency-Key on a Sume bulk create returns 202 and the old queue, not 200. Derive the key from the batch: safe retries, deliberate reruns.
One Idempotency-Key for an Omni 360p draft and 720p final: it 409s
Reusing the draft's Idempotency-Key on the 720p final returns 409 idempotency_conflict. Key naming that keeps draft and final jobs apart, with a Python helper.
Timeline plan for a 40-second Omni stitch: four segments, one minute
Run Sume's unbilled timeline plan on four 10-second Omni clips to see segment_count, billable_minutes and the cost before you render. Request body included.
Split a 40-second brief into four Omni prompts, one character block
A Python script that turns one 40-second brief into four 10-second Gemini Omni 1.1 Flash request bodies for Sume, with one shared character block.
Fix a first frame with Ideogram 4.5, then send it to Omni image_url
Correct text or a prop in a still with Ideogram 4.5 on Sume, then use the edited image as the Gemini Omni 1.1 Flash first frame. Two jobs, one shot.
Edit a finished Omni clip with video_url instead of re-rolling it
Send an existing clip as video_url to gemini-omni-flash-1.1 on Sume with an edit prompt. Resolution defaults to 720p; send no duration or aspect_ratio.
Fields Omni rejects on Sume: generate_audio false, bitrate_mode
Which request fields Sume's gemini-omni-flash-1.1 refuses or lacks: generate_audio false, bitrate_mode, reference_audio_urls, plus edit-mode rules.
Chain a 30-second render, trim and captions: three jobs, three keys
Generate, trim and caption an AI clip through the Sume API as three separate jobs, each with its own Idempotency-Key, status poll and result read.
Cancel a video chain midway: 409 job_generation_already_started
Cancel works only before generation starts. In a render, trim and captions chain, cancel queued jobs, let started jobs finish, and stop submitting steps.
Retry an image edit after a timeout: same key, same payload
After a client timeout on an image edit, resend the same payload with the same Idempotency-Key. If you change the prompt, change the key.
Retry a video-trim: same key for the same body, new key for new start
A trim that timed out can be retried with the same Idempotency-Key and body. Changing start, duration or precision is a new operation and needs a new key.
Redelivered job.completed must not start the trim twice
Redeliver re-sends the same job's terminal event with a fresh signature. Dedupe on job_id and derive the next step's Idempotency-Key from it.
Start the trim step from a job.completed webhook: Python verifier
Let Sume's signed job.completed webhook trigger the next chain step. A stdlib Python verifier that refuses an empty secret, plus dedupe on job_id.
AI video generator with no sign-up: what Sume needs before clip one
Sume cannot render video without an account, an API key and a funded balance. Four public reads work with no key, so you can check models first.
AI video generator from image: the URL checklist before you submit
Image-to-video on Sume needs a public HTTPS image URL. Five checks, the two error codes when Sume cannot fetch it, and the first-frame request body.
Music API image_url null: clear a reused request body, with Python
Send image_url as null on Sume music requests only to clear an image from a reused request object. A short urllib script posts to the Music Router.
Which Sume audio calls can sync-wait 30 s? A map vs 150 ms claims
Detach, timeline audio, ingest, music and TTS: which can return in a 30 s sync wait, which are async jobs, and what a 150 ms end-to-end claim leaves out.
Text-to-video API in Node: submit, poll and download with a deadline
A runnable Node 18+ script that submits a text-to-video job to Sume, polls it with a deadline, and saves the MP4. No dependencies and no top-level await.
Vertical 9:16 text-to-video API: a 12-second Wan 3.0 clip, priced
A 12-second 9:16 text-to-video request on Sume with Wan 3.0 costs $0.75 at 480p, $1.50 at 720p and $3.00 at 1080p. Full body and the other models that fit.
AI video generator from text: the three fields that set the price
In a text-to-video request on Sume, model, resolution and duration set the price. Prompt length and aspect ratio do not. Worked Wan 3.0 and Omni numbers.
Omni and Seedance clips in one timeline: the fps resample warning
Clips from two video models can have different frame rates. Sume's timeline warns with output_fps_resamples_sources; probe each clip, then set output.fps.
script_text, words, cues or segments: which caption input to send
Sume captions take only one of script_text, words, cues, segments. Your pick decides whether speech-to-text runs and what happens on a silent clip.
Which URL goes into video-captions after a trim: the new artf_
After video-trim, caption the new video_url from the trim result, not the source render. It is a new artifact on media.sume.com and a public HTTPS URL.
How long to wait for a Sume job webhook before you start polling
Job webhooks retry 10 times, 30 seconds apart, with a 10-second timeout each. Start your poll fallback at about 6 minutes, and here is the arithmetic.