AI video generator app: four server calls, key never on the client
An AI video app on Sume needs four server-side calls: submit, poll, download and balance. The key stays on your server, never in the browser or mobile app.
If you are building an AI video generator app on Sume, your backend needs four calls, and your mobile or web client needs none of them directly. The app talks to your server; your server talks to api.sume.com with the API key. The authentication docs say never to put an API key in frontend JavaScript, a mobile app, a support ticket or a screenshot.
The four calls
Every call carries Authorization: Bearer $SUME_API_KEY.
| Step | Call | Why your server needs it |
|---|---|---|
| List models | GET /v1/videos/models | Fill the model picker with each model's resolutions, aspect ratios and durations |
| Submit | POST /v1/videos | Returns a job id, a polling URL and status pending |
| Poll | GET /v1/videos/{jobId} | Status moves to completed or failed; read usage.cost when done |
| Download | GET /v1/videos/{jobId}/content?index=0 | Returns the MP4 bytes with the key header |
Add a balance check
GET /v1/balance returns the workspace balance in USD. Check it before you show a Generate button, because a submit that cannot reserve its estimated cost returns 402 insufficient_credits before any provider work starts. Do not invent a top-up call: the credits docs say a top-up is a dashboard operation, and the public API gives balance and usage reads only.
Do not poll from every phone
Video generation takes from 30 seconds to several minutes, according to the docs. Let your backend own the polling, or pass callback_url (HTTPS only) and let Sume POST to your server when the job reaches a terminal state. Your app then reads the result from your own store. Send an Idempotency-Key on submit so a retry from a flaky mobile connection replays the original job instead of paying for a second one.
Respect the queue
Generation concurrency is set by the workspace plan: the admission docs list 1 for Free, 4 for Pro, 8 for Startup and 20 for Scale. Extra valid jobs wait as queued while queue capacity remains, then new submits fail with 429 queue_full. Tell your users a clip is queued rather than failed, and read generation_limits on the submit response to size your own waves.
Errors your UI should translate
Your app will meet the same errors that any client of the API does, so give each a plain message. 402 insufficient_credits should say the workspace balance is too low. 429 queue_full should say the queue is full and the user can try again when a job finishes. 400 invalid_request is a bug in your form, not the user's fault. A failed job carries a public error category, and the docs list the next action for each: validation means correct the input, quota means add funds or lower the cost, and generation_timeout means poll the status or retry later.
Include the request_id from the error body in your logs and in any support request. The docs say it is safe to share with Sume support, and it is the thing support will ask for.
Keep your own record per clip: your user id, the Sume job id, the model, the settings and the estimated cost. The job id is enough to fetch the status and the result later through GET /v1/jobs/{id}/status and GET /v1/jobs/{id}/result, which show the same job as the video polling URL. That record is also what lets you reconcile your estimate against usage.cost and the usage ledger at the end of the month.
Sources
Related posts
More in Developers
- 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.
- 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.
- 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 seed on Sume: no model accepts one, lock shots with frames
Every Sume v1 video model reports seed false and rejects the field. To repeat a look, lock first and last frames, references, resolution and a stable prompt.
Written by Sume