Most "AI video API" write-ups stop at a single request. An agent needs more: a way to choose, a way to price, a way to wait, and a way to fail safely. This is the sequence that works against TurboMax's MCP server, written so an agent (or the person configuring one) can follow it step by step.
The sequence
list_models— filter bytype(image,video,audio) and, if you know it,task(for exampletext-to-videoorimage-to-video). Each result lists the allowedaspectRatios,resolutions,durationRangeandmodes. Use these values exactly; the server rejects anything outside what a model declares rather than silently adjusting it.estimate_cost— passmodelId, anddurationandresolutionfor video. The figure is approximate; the real amount is held when the job starts.- (Optional)
upload_source_media— for image-to-video, image editing or video-to-video, upload the source and keep the returnedurl. Only files uploaded through TurboMax are accepted as sources. generate_media— sendmodelId, the user'sprompt, the task parameters, andmaxCredits. The response contains ataskIdand the exactcostthat was held.get_taskwithwaitSeconds(up to 55). Repeat whilestatusisprocessing.- Use the result. When
statusiscompleted,resultUrlis the file. It is a time-limited link, so download it or hand it over promptly.
{ "name": "generate_media",
"arguments": {
"modelId": "<id from list_models>",
"prompt": "A paper boat drifting down a rain-soaked street, slow push-in",
"task": "text-to-video",
"duration": 5,
"maxCredits": 150
} }
Rules an agent should follow
- Use the person's words. Do not add scenes, styles or subjects the user did not ask for. The server never writes a prompt for the caller and refuses an empty one.
- Always set
maxCreditswhen no human approves each call. It is checked against the exact estimate before a credit is held, and a refusal charges nothing. - Read before you spend.
get_walletreturns the balance and today's usage against the account's daily limits. - Do not loop on errors that will not change.
prompt_rejected,api_key_scopeandpayment_requiredneed a different prompt, key or account state, not a retry.
How failures behave
| Situation | Result | Charged? |
|---|---|---|
Cost above maxCredits | cost_exceeds_max | No |
| Balance too low | insufficient_credits with balance and required amount | No |
| Prompt violates policy | prompt_rejected | No |
| Rate limit or daily cap | rate_limited or a daily-limit code | No |
| Job fails or times out upstream | status: failed | Refunded in full |
You cancel with cancel_task | status: canceled | Hold released |
| Job completes | status: completed | Settled to the actual cost |
retry_task re-runs a failed or cancelled job as a new job with a fresh hold, so it spends credits again.
Choosing a model
Do not hard-code one. Catalogues change: models are added, repriced and retired. An agent that calls list_models each session always works from the current list, and can pick by constraint ("cheapest model that supports image-to-video at 1080p") instead of by name. For help comparing model families see the AI video model comparison and what AI video generation costs.
Giving an agent access safely
Create a read-only key first and let the agent browse. When it must generate, create a separate generate key (this requires a paid account), keep the wallet balance to what you are willing to lose, and revoke the key when the task is done. A key can never change the account, billing or settings. Setup instructions are in connecting Claude, Cursor and VS Code; the overview is in the MCP server guide.