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.
Stripe idempotency key length (255) and Sume's key rules
Stripe allows keys up to 255 characters. Sume generation keys are 1-255 printable ASCII and optional; crawl keys are required and capped at 200.
Telegram sendLivePhoto: 10 s, 10 MB and trimming a clip
Telegram's sendLivePhoto video must be 10 seconds or less and 10 MB or smaller. Sume's video trim sets length and frame size; it has no byte-size target.
Temporal activity cancel: Sume job_generation_already_started
When Temporal cancels an activity, a Sume job may already be generating. Cancel returns 409 job_generation_already_started; let it finish and keep the artifact.
Temporal BlobSizeLimitError: pass the Sume artifact URL, not bytes
Temporal Cloud allows 2 MB per payload. Pass the Sume job_id and media.sume.com artifact URL through activities and signals, never video bytes.
Text to dialogue API: continuity between requests on Sume
Sume's TTS has no previous_text field. Keep a line seamless with one longer transcript, or join separate takes with a gapless Timeline audio concat.
TikTok Research API documentation: 30-day dates vs Sume date_posted
The Research API takes start_date and end_date up to 30 days apart. Sume's tiktok_search_keyword takes one fixed date_posted value instead.
TikTok Research API access: is_random order vs Sume order
The Research API returns videos by decreasing ID unless is_random is true. Sume's order=play_count sorts a bounded 24-item sample, not a full ranking.
TikTok Research API rate limit: max_count 100 vs Sume's 24
The Research API returns up to 100 videos per call (max_count). Sume's tiktok_search_keyword returns at most 24 items over 3 feed pages per call.
Twitch 2K clips: trim a 1440p clip without setting output
Video trim's output width and height are limited to 256-2160, so a 2560-wide 1440p clip cannot be conformed. Omit output and the source size is kept.
Vercel 413 FUNCTION_PAYLOAD_TOO_LARGE with Sume video
Vercel Functions cap request and response bodies at 4.5 MB. Do not proxy a generated video through one; hand the client the media.sume.com URL instead.
Vercel function max duration 800s: Sume wait budget
Vercel Pro and Enterprise allow 800s, with 1800s in beta. Sume still caps a blocking wait at 30s, so video jobs need a poll loop with its own deadline.
Vercel Queues retry can resubmit a paid Sume job
A Vercel Queues consumer that times out is redelivered, and maxDeliveries is unlimited by default. Reuse one Idempotency-Key per message so Sume bills once.
xAI video status done/expired vs Sume completed/failed
xAI's Grok Imagine video status values are pending, done, expired and failed. Sume uses pending, in_progress, completed, failed and cancelled. Port a poll loop.
Sora Videos API replacement: seconds and size on Sume
OpenAI removed the Videos API on 2026-09-24. Map its seconds and size fields to Sume's duration, resolution and aspect_ratio; size returns 400 on Sume.
Sora video.completed webhook to Sume job.completed
Sora emitted video.completed and video.failed. Sume sends job.completed, job.failed and job.canceled with an x-sume-webhook-signature header. Map the handler.
Sora input image must match size: the Sume frame_images rule
Sora's input image was the first frame and had to match the video size. Sume uses frame_images plus aspect_ratio, and rejects size on v1 models.
Wan 3.0 reference video requirements: 15 seconds and 16 fps
On Sume, wan-3.0 reference videos total 15 seconds or less and need 16 fps or more, up to 5 clips. Check each clip with video inspect and trim to fit.
Higgsfield Genjutsu API on Sume: one source video, 1 to 8 images
Genjutsu Motion Transfer on Sume needs exactly one source video plus 1 to 8 reference images. Text-only or malformed bodies are not valid. Request shapes below.
Runway Enhance Frame Rate: 300 s cap and credits vs Sume fps
Runway's Enhance Frame Rate takes inputs up to 300 seconds at 1 credit per 2 seconds. Sume's Timeline sets output.fps to 24, 25, 30 or 60. Compared.
gpt-image-2 transparent background: OpenAI preview vs Sume
OpenAI put transparent backgrounds for gpt-image-2 in preview (png or webp). On Sume, the background parameter is listed for ChatGPT Image 2.5, not gpt-image-2.
GPT Image output_compression: OpenAI has it, Sume returns 400
OpenAI lets jpeg and webp take output_compression 0-100. Sume's docs say it is not served in v1 and sending it returns 400 unsupported_parameter.
GPT Image edit with a mask and several images: which is masked?
OpenAI applies the mask to the first of several input images. Sume forwards input_references in order with mask_url, so put the image to edit first.
GPT Image resolution above 2560x1440: experimental, and Sume's cap
OpenAI marks GPT Image sizes above 2560x1440 as experimental. Sume's 2.5 custom pixels accept up to a 3840 edge, so check the five size rules before you send.
TTS locale vs language field: getting an en-GB accent
Cartesia's locale field picks a regional accent such as en-GB on Sonic 3.6. Sume's TTS request has a language field only, so pick the accent via the voice.
TTS voice-language mismatch warning: confirm, then retry
Sume's TTS warns when a voice's language differs from `language`. No job or charge exists yet; after the user agrees, retry with `confirm_language_mismatch`.
Gemini /v1beta/voices vs finding a voice id on Sume
Gemini added a Voices endpoint on 2026-09-22. Sume has no separate voices list route; list avatars and use one whose `voice.status` is `ready`.
TTS invalid_voice_id 400: a voice name from another vendor
Sume returns 400 `invalid_voice_id` for a voice name that is not a UUID or `voi_` id, before any job or credit. Copy an id verbatim or send an avatar.
AI music prompt max length: 5000 characters on Sume
Sume's Music Router accepts a prompt of 1-5000 characters. What to spend them on: a seven-axis brief, section markers and exclusions, in one positive prompt.
Music API timeout at 30 seconds: poll or webhook instead
A song can outlast Sume's 30-second wait. The wait bounds the HTTP call, not the job, so submit async and poll the status URL, or use a webhook.
TikTok AI label or your own caption, sticker or watermark
TikTok lets you disclose AI content with its AIGC label or your own clear caption, sticker or watermark. Burn a caption or add an overlay plate with Sume.
TikTok AI label for cropping or reframing: not needed
TikTok says disclosure isn't needed for small edits like color correction, reframing or cropping. See which Sume crop, fit and trim settings are those edits.
Instagram API poll_attachment on Reels: how the add-on works
Set poll_attachment when creating a Reel container: two to four options, 3 days by default, Facebook Login only. What Sume prepares before that call.
Instagram API is_comment_prompt_used: comment prompts on Reels
Set is_comment_prompt_used to true on the media container to attach a comment prompt, then read replies from prompt_response. One add-on per media, no poll.
Instagram media_publish config_issue CAPTION_NOT_ATTACHED
A media_publish call can succeed with the caption dropped. The response then carries config_issue CAPTION_NOT_ATTACHED. What it means and a burned-in fallback.
graph.instagram.com 400: parameter only for Facebook Login
Requests to graph.instagram.com with a Facebook-Login-only parameter now return 400 naming it, instead of being ignored. How to read the error and fix the call.
Instagram publish error: linked Facebook account restricted
Meta added a publishing error: the linked Facebook account is restricted and cannot publish video. What it blocks and how to post stills from a clip meanwhile.
Instagram API media_url missing: copyrighted audio and reels
Since 2026-07-30 Instagram omits media_url for video with copyrighted audio or reels with downloads off. Treat it as optional and import files you own.
Bluesky video length limit: 10 minutes, and how to trim to fit
Bluesky's app sets VIDEO_MAX_DURATION_MS to 10 minutes, and 1.132.0 removed the 10-minute gate. Trim longer clips with Sume video trim first.
Bluesky video format not supported: the accepted MIME types
Bluesky's app accepts video/mp4, video/mpeg, video/webm, video/quicktime and image/gif. For anything else, re-encode to MP4 with Sume video trim.
MCP server/discover against Sume's hosted endpoint
The 2026-07-28 MCP spec adds server/discover. Sume's hosted server does not implement it and answers -32601; read initialize and tools/list instead.
MCP listTools nextCursor: Sume returns a single page
TypeScript SDK 2.2.0 follows nextCursor in listTools(). Sume's tools/list returns a tools array with no cursor, so the walk ends after one request.
MCP subscriptions/listen: Sume has no push stream to join
MCP's 2026-07-28 spec adds subscriptions/listen for change notifications. Sume's hosted MCP answers POST only and declares listChanged false.
MCP Apps _meta.ui.resourceUri: what a Sume tool call shows
MCP Apps tools point at a ui:// resource for the host to render. Sume's hosted MCP lists plain tools, so a host shows the tool result, not an app.
MCP expectedIssuer with client credentials: Sume uses an API key
MCP TypeScript SDK 2.2.0 adds expectedIssuer to machine-to-machine providers. Sume's OAuth is authorization_code only; headless agents use an API key.
OAuthFlowError issuer mismatch in the MCP Python SDK 2.2
Python SDK 2.2 rejects authorization server metadata whose issuer is not the server's origin. Sume's metadata sets issuer to the MCP origin.
MCP Python SDK idle session 404: what it means for Sume jobs
Python SDK 2.2 closes stateful sessions idle for 30 minutes, then 404s. Sume's hosted MCP is POST-only; re-poll jobs_wait with the same ids, never resubmit.
Claude Code auto mode with Sume's MCP: paid-call gates still apply
In Claude Code auto mode a classifier reviews each action. On Sume's MCP, paid calls still need idempotency_key, and dry_run and max_spend_usd stay available.
claude -p --permission-prompt-tool with Sume paid jobs
Headless claude -p can route permission prompts to an MCP tool. For Sume paid jobs, keep idempotency_key stable and wait with jobs_wait in 55s slices.