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.
GPT Image 2.5 mask checklist: same size, alpha, under 50MB
Check your mask before a paid GPT Image 2.5 edit: same size and format as the image, an alpha channel, under 50MB. A short Python preflight for Sume mask_url.
Image job still running after 50 seconds: slow or stuck?
Sume's docs say an image still running at 50 seconds is usually stuck, not slow. What to read first, when not to resubmit, and when to cancel.
Instagram Reels audio_name: you can rename the audio only once
Meta lets you rename a Reel's original audio once, in the container or on the audio page. Decide the name before publish and detach the track with Sume.
Instagram Reels: lint hashtags and @ tags before the API errors
Meta caps a caption at 2,200 characters, 30 hashtags and 20 @ tags, and the API now returns separate errors. A 20-line check to run before you publish.
Instagram Reels thumb_offset is in milliseconds: pick the frame first
thumb_offset takes milliseconds, defaults to 0, and loses to cover_url. Preview candidate frames with Sume video_frames before you publish the Reel.
Instagram Reels user_tags API: usernames only, not on-screen text
user_tags on a Reel tags public accounts by username; x and y apply to images and stories. A handle burned into the video is not a tag. How to do both.
Jan allow-all MCP permissions and smart routing with Sume tools
Jan can auto-approve every MCP tool call and narrow which servers it queries. What each does to paid Sume calls, and how to keep a spend check.
Jan MCP tool call timeout of 30 seconds vs Sume jobs_wait
Jan times out MCP tool calls after 30 seconds by default, while a Sume jobs_wait slice can run 50 to 55 seconds. How to set them so a render never looks failed.
Does a canceled Sume job send a webhook? Jobs do, runs do not
A canceled generation job delivers job.canceled with status ERROR, but a canceled or skipped Format, Action or Agent run sends no webhook. Handle both paths.
Sume webhook retry schedule: jobs every 30 s, runs exponential
Sume job webhooks retry up to 10 times about 30 seconds apart; run webhooks back off exponentially to one hour. What each gives your endpoint to recover.
Kimi Code CLI YOLO and AFK modes with paid Sume tools over MCP
Kimi auto-approves MCP tool calls in YOLO and AFK modes. What that means for a Sume server with write access, and the limits to set first.
Kimi mcp test fails on Sume: URL, auth and scope checklist
If kimi mcp test fails or shows no Sume tools, check the endpoint URL, run kimi mcp auth, then separate a read-only grant from a broken connection.
Luma DELETE /generations/{id} returns 204: what Sume does instead
Luma permanently deletes a generation with DELETE and answers 204. Sume has no job delete; it cancels before generation starts. What that means for cleanup.
Fine-tune MiniMax H3 with a LoRA: data grid, recipe and serving
MiniMax points to an experimental miles-diffusion LoRA recipe for H3: 1344x768, 24 fps, 17n+5 frames, 8 x H200. The data rules and how to serve it.
Retrying a Sume music job: Idempotency-Key and no double charge
Retry a timed-out Sume music request with the same Idempotency-Key and get the original job back. Lyria 3.5 varies per call, so never use a new key.
Nano Banana edit slow? Thinking can't be turned off, expect 202
Google says Nano Banana thinking cannot be disabled. On Sume a call that outlasts 30 seconds returns 202 with a job id. How to handle both without paying twice.
Runway API X-Runway-Version header: dated versions vs Sume /v1
Runway requires an X-Runway-Version date header and supports an old version for four months. How that differs from the /v1 path versioning Sume uses.
subscribeFormatRun on a failed run: it resolves, it does not throw
subscribeFormatRun resolves with status failed instead of throwing; it only throws when create is refused or the wait times out. How to branch in TypeScript.
subscribeFormatRun timeline: true doubles your status reads
Setting timeline: true on subscribeFormatRun reads the phase timeline on every poll, doubling requests. Read budget math, 429 behavior and when to turn it on.
Verify a Sume avatar video webhook in Node and TypeScript
A Node server that refuses an empty secret, checks the x-sume-webhook-signature HMAC over timestamp.rawBody, then fetches the avatar video result by job_id.
waitForRun and 429 or 503 on a status read: it keeps polling
A 429 or 5xx on a status read does not fail the run. waitForRun tolerates 6 consecutive transient read failures and keeps waiting. Options and what to log.
Wan 2.2 TI2V-5B in Diffusers: 121 frames, 24 fps, 24GB GPU
A working Diffusers example for Wan2.2-TI2V-5B: 704x1280 portrait frames, 121 frames at 24 fps, 24GB VRAM minimum, and when to use a hosted route instead.
Webhook returns 503 with Retry-After: how Sume spaces the retries
If your webhook endpoint answers 429 or 503 with Retry-After, Sume run webhooks wait at least that long, capped at one hour. Here is how to shed load safely.
Sume webhook_url 400: localhost, http, credentials, alias clash
Why a Sume create call rejects webhook_url with 400 invalid_request: localhost, private IPs, http, credentials in the URL, or conflicting webhook_url aliases.
A/B test two LLMs on one Sume Format input with the model field
Run one Sume Format twice with a different model, then compare the receipt's model and debited cost. A short Python script with an Idempotency-Key and polling.
Avatar job webhooks during secret rotation: accept either signature
During a Sume secret rotation the signature header carries two sume-v1 entries. Accept the delivery if any one matches; Node verifier code included.
Avatar 409 idempotency_conflict: reuse a key only for exact retries
Sume returns 409 idempotency_conflict when a key is reused with a different payload. When to keep a key, when to mint a new one, and how to name batch keys.
Cancel a completed job: 409 job_not_cancelable vs already started
Sume returns 409 job_not_cancelable when you cancel a finished job, and job_generation_already_started mid-run. How to tell them apart and handle each.
cancel_url is null on a processing job: when Sume allows cancel
Why a Sume job in processing can show cancelable false and cancel_url null: cancel depends on whether generation work started, not the status label.
Sume images API n=5 returns 400 though the docs say up to 10
The Image API docs say n up to 10, but the catalog range is 1 to 4 for most models, 1 for Grok and 1 or 4 for Soul. The error text and a loop that batches.
Instagram Reels 300 MB file limit: bitrate budget by length
Instagram's Reels API caps files at 300 MB and 25 Mbps. Past about 96 seconds the file size binds. The average bitrate per length, and what Sume can check.
Instagram Reels API frame rate 23 to 60: set fps in Sume
Meta's Reels API accepts 23 to 60 fps. Sume trim and Timeline output fps takes 24, 25, 30 or 60, and warns when it resamples. What to pick for a Reel.
Instagram Reels API codec rules: HEVC or H.264, 4:2:0, closed GOP
Meta's Reels API wants MOV or MP4, HEVC or H.264, progressive, closed GOP, 4:2:0. What Sume's exact and keyframe trims produce, and what the docs leave open.
Instagram Reels over 15 minutes: split for the API with video trim
The app allows Reels up to 20 minutes; the Reels API stops at 15. Sume trim outputs up to 900 seconds, exactly 15 minutes. How to split a 20-minute video.
Localize on-screen text per language: Python caption fan-out
Burn one set of translated cues per language onto a clean clip with Sume: one job each, its own key, asyncio fan-out, $0.20 a job. A runnable script.
MiniMax image-01 API: 9 images, 1,500 characters, 24-hour URLs vs Sume
MiniMax image-01 takes a 1,500-character prompt, 1 to 9 images, 512-2048 px sizes and returns URLs that expire in 24 hours. Sume's Image API limits compared.
music_create over MCP: dry run, idempotency key and jobs_wait
How the hosted MCP music_create tool works: prompt inside payload, dry_run preview, a required idempotency_key, and jobs_wait in 55-second slices.
next_poll_after_seconds is null on a finished job: fix the poll loop
Sume sets next_poll_after_seconds to null once a job is terminal, so sleep(null) crashes naive loops. Stop on terminal, then read result_ready.
Queued Sume job: retry_after_seconds is capped at 30 seconds
For a queued job that is not yet available, Sume reports retry_after_seconds up to 30 and uses it as next_poll_after_seconds. Honor it, never sleep longer.
Batch Seedance and Kling jobs: generation_limits and wave_size_hint
Submitting many Seedance or Kling clips at once? How Sume's generation_limits fields give a safe in-flight budget, and why wave_size_hint is not concurrency.
Seedance or Kling job failed: could not download an input media URL
A Seedance or Kling job can fail with 'Could not download an input media URL'. Why Sume rejects a frame or reference URL, and a preflight check for it.
Seedance and Kling submit errors: which to retry and which to fix
A Sume video submit can fail with 402, 429 queue_full, 429 rate_limited or 400. Which to retry with the same key and which need a changed request.
Sume image API 400 "accepts at most N input_references"
GPT Image 2.5 takes 16 references on Sume, most edit models take 10, text-only models take none. The 400 you get and a pre-flight check.
SumeRunTimeoutError: the run keeps billing, resume with its run id
In @sume-com/sdk, SumeRunTimeoutError means your wait ended, not the run. It carries runId and lastStatus: store them and read the receipt later.
Sume SDK idempotency key: idempotencyKey option or header?
subscribeFormatRun takes an idempotencyKey option and generates one for you; generated operations like generateVideoV1 need the idempotency-key header.
TikTok publish_id (64 chars): store it next to the Sume job id
TikTok's publish_id can be up to 64 characters and drives status polling. Keep it with the Sume job id and Idempotency-Key so a retry never double-posts.
Wait for an avatar video job with the SDK: waitForJob and its timeout
Avatar jobs need waitForJob, not waitForRun. Defaults, the 20-minute timeout, and why a SumeJobTimeoutError neither cancels nor refunds the render.
Webhook handler slower than 10 seconds: duplicate Sume deliveries
Sume gives each webhook attempt 10 seconds, then retries up to 10 times, 30s apart. A slow handler that succeeds late still gets duplicates. Ack first.