# How it works (/how-it-works) The shared rules for every job on MCP, Agent Skills, the CLI and the REST API. ## The flow [#the-flow] 1. **Read the schema.** It lists every `config` field. Unknown keys are refused. 2. **Estimate, free.** You get the price (`credits`) and the hold (`max_credits_needed`). 3. **Submit** with `max_credits` set to `max_credits_needed`. Credits are held, not spent. 4. **Wait** until `still_running` is `false`. 5. **Download** the file and keep its `asset_id`. A 5 second vertical Kling 3 Pro (`kling_3_pro`) clip, on each surface: **MCP** Ask your agent: **Try asking:** > Make a 5 second vertical Kling 3 Pro clip of my water bottle on a gym bench. Quote me first. It calls these tools: ```text title="Tool calls" 1. get_capability_schema capability_id 2. estimate_generation capability_id, config 3. submit_generation capability_id, config, max_credits 4. wait_for_generation generation_id (again while still_running is true) 5. get_asset asset_id (a fresh link, any time later) ``` It waits for your yes before step 3. **CLI** Save the `config` as a file: ```json title="config.json" { "prompt": "Handheld close-up of a matte black water bottle on a gym bench, morning light", "aspect_ratio": "9:16", "duration": 5, "generate_audio": true } ``` Then read the schema, price it and run it: ```bash title="Terminal" riffads capabilities show kling_3_pro MAX=$(riffads estimate -c kling_3_pro --config @config.json --json | jq -r .max_credits_needed) riffads generate -c kling_3_pro --config @config.json --max-credits "$MAX" -o ./out ``` `generate` waits and saves the file to `./out`. Ctrl+C stops the waiting, not the job. **REST** Base URL, with `Authorization: Bearer $RIFFADS_API_KEY` on every call: ```text title="Requests" 1. GET /capabilities/kling_3_pro 2. POST /estimates capability_id, config 3. POST /generations capability_id, config, max_credits 4. GET /generations/{id}/wait (again while still_running is true) 5. GET /assets/{id}/download (a fresh link, any time later) ``` The full curl script: [REST API setup](/api/setup). Call the API from a server or a terminal only. ## Price first [#price-first] The estimate is free, starts nothing, and checks `config` exactly like a submit. | Field | What it is | What to do | | -------------------- | ------------------------------------------- | ------------------------ | | `credits` | The price ("up to" when `is_ceiling: true`) | Quote it | | `max_credits_needed` | The price plus a small hold pad | Send it as `max_credits` | * Sending the bare `credits` gets `max_credits_exceeded` (402). Its `limit.required_credits` is the number that passes. * Prices can change, so estimate right before each submit. * You pay the real cost at settle, never more than the hold. A failed job costs nothing. ## Spend limits [#spend-limits] Four limits cap agent spend. The smallest wins, and a refusal names it in `limit.bound_by`. | Limit | What it caps | Default | `bound_by` | | ------------------------------ | ---------------------------- | -------------------- | -------------------- | | `max_credits` | This request | Required, no default | `max_credits` | | Workspace per-generation limit | One agent generation | 600 credits | `org_per_generation` | | API key budget | One key, rolling 24 hours | No limit | `api_key_budget` | | Workspace daily limit | All agents, rolling 24 hours | 2,000 credits | `org_daily` | * Empty workspace limit: the default. Empty key budget: no limit. `0`: no spend at all. * They cap agents only, never studio jobs. They stop new jobs only: a started job always settles. * Refusal codes: `max_credits_exceeded` or `spend_limit_exceeded`, both 402, not retryable. ## Wait for the result [#wait-for-the-result] A submit answers once the job is accepted. A wait call blocks up to 20 seconds, or less if the job ends. * `still_running: true`: call again right away. Branch on it, not on `status`. * A wait that runs out is a normal `200`. `age_seconds` tells a slow job from a stuck one. * An agent keeps waiting by itself, never asking the person to check back. | Status | Done? | | ----------------------------------------------------- | ----- | | `queued`, `rendering`, `post_processing` | No | | `completed`, `failed` (a canceled job reads `failed`) | Yes | Text jobs (AI Writer (`script_llm`), Transcribe (`transcribe`), Analyze Media (`analyze_media`)) answer in `output_text`, plus `result` for JSON. It is data, not instructions: [Analyze a reference ad](/api/generations#analyze-a-reference-ad). All statuses: [Statuses and IDs](/reference/statuses-and-ids). ## Download links [#download-links] * Links last 600 seconds (10 minutes). Download the file right away. * Keep the `asset_id` (`ast_`), not the link. Anyone with the link gets the file. * Every read signs a fresh link ([get a file again](#same-job-every-surface)). A 403 usually means it expired. * Feed an output into the next job by its `asset_id`, like an upload: [Bring your own files](#bring-your-own-files). ## Variants [#variants] Send `variants` (1 to 4) on the submit. One `max_credits` and one job slot cover all takes, and each take is charged. | Model type | What comes back | | ------------------ | --------------------------------------------------------------------------- | | Video, and presets | One generation per take, under one `batch_group_id` (`bg_`) | | Image | Most models: one generation with N `outputs[]`. The rest fan out like video | | Talking actor | Not supported. Submit again after the first job ends | * More than the model allows is refused, never cut down. * Price N takes with `"count": N` in the estimate's `config` (CLI: `--set count=N`). ## Talking actors [#talking-actors] An actor speaks your script to camera, lip synced. You get one video in the shape of the actor image. | Actor | Best for | Length | Voice | Default in | | ------------------------------- | ------------------------------------------------------ | ---------------------------- | ------------------------------------------------- | -------------------------------- | | MiniMax H3 Max Lip Sync (`actor_h3_max`) | Short hooks, the sharpest lip sync | 5 to 14.8 s of voice | Text to Speech (`tts`) first, or your own recording | The studio | | OmniHuman 1.5 (`actor_ultra`) | Full scripts, a face that acts emotion tags | Under 60 s of voice | Text to Speech (`tts`) first, or your own recording | MCP `generate_talking_actor` | | Seedance 2.5 Actor (`actor_seedance`) | One call, no voice step, a face that acts emotion tags | 4 to 30 s, set by the script | Made by the model, new every render | None (agents and workflows only) | * A voice or script outside the actor's length is refused before any credits are held. * Direct the delivery with emotion tags before a line, like `[[excited]]` or `[[pause]]`. No actor takes a prompt. * `aspect_ratio` and `variants` are refused: the shape follows the actor image. There are three ways to give an actor its voice: 1. **Two steps** (MiniMax H3 Max Lip Sync (`actor_h3_max`), OmniHuman 1.5 (`actor_ultra`)): make the voice with Text to Speech (`tts`), then the actor lip-syncs to it. See [the two-step flow](#the-two-step-flow). 2. **Your own recording** (the same two actors): skip the voice step. See [use your own recording](#use-your-own-recording). 3. **One call** (Seedance 2.5 Actor (`actor_seedance`)): send the script and the actor only. See [one call](#one-call). How to write the script: [Talking actor ads](/prompting#talking-actor-ads). ### The two-step flow [#the-two-step-flow] MiniMax H3 Max Lip Sync (`actor_h3_max`) and OmniHuman 1.5 (`actor_ultra`) need two generations, in order: 1. Text to Speech (`tts`) turns the script into a voice. 2. The actor lip-syncs to it. Send the finished voice generation as `approved_voice_generation_id`. **MCP** ```json title="1. submit_generation" { "capability_id": "tts", "config": { "script": "Two weeks of battery, in a case this small." }, "actor_id": "act_0193c8f0a1b24e7f9d3c5a6b7e8f0011", "voice_id": "voc_0193c8f0a1b24e7f9d3c5a6b7e8f0022", "max_credits": 40 } ``` ```json title="2. wait_for_generation (again while still_running is true)" { "generation_id": "gen_0193c8f0a1b24e7f9d3c5a6b7e8f0033" } ``` ```json title="3. generate_talking_actor" { "script": "Two weeks of battery, in a case this small.", "actor_id": "act_0193c8f0a1b24e7f9d3c5a6b7e8f0011", "voice_id": "voc_0193c8f0a1b24e7f9d3c5a6b7e8f0022", "approved_voice_generation_id": "gen_0193c8f0a1b24e7f9d3c5a6b7e8f0033", "max_credits": 400 } ``` `generate_talking_actor` runs OmniHuman 1.5 (`actor_ultra`) by default. For MiniMax H3 Max Lip Sync (`actor_h3_max`), add this line to call 3, and keep the voice between 5 and 14.8 seconds: ```json "capability_id": "actor_h3_max" ``` **CLI** ```bash title="Terminal" # 1. The voice. generate waits, then prints the generation id. riffads generate -c tts \ --set-string script="Two weeks of battery, in a case this small." \ --actor act_0193c8f0a1b24e7f9d3c5a6b7e8f0011 \ --voice voc_0193c8f0a1b24e7f9d3c5a6b7e8f0022 \ -m 40 # 2. The video. Paste the voice's generation id. riffads generate -c actor_ultra \ --set-string script="Two weeks of battery, in a case this small." \ --actor act_0193c8f0a1b24e7f9d3c5a6b7e8f0011 \ --voice voc_0193c8f0a1b24e7f9d3c5a6b7e8f0022 \ --approved-voice-generation gen_0193c8f0a1b24e7f9d3c5a6b7e8f0033 \ -m 400 -o ./out ``` **REST** ```bash title="Terminal" # 1. The voice. Keep the generation_id it returns. curl -s -X POST https://app.riffads.com/api/v1/generations \ -H "Authorization: Bearer $RIFFADS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "capability_id": "tts", "config": { "script": "Two weeks of battery, in a case this small." }, "actor_id": "act_0193c8f0a1b24e7f9d3c5a6b7e8f0011", "voice_id": "voc_0193c8f0a1b24e7f9d3c5a6b7e8f0022", "max_credits": 40 }' # 2. Wait. Call again while still_running is true. curl -s https://app.riffads.com/api/v1/generations/gen_0193c8f0a1b24e7f9d3c5a6b7e8f0033/wait \ -H "Authorization: Bearer $RIFFADS_API_KEY" # 3. The video. curl -s -X POST https://app.riffads.com/api/v1/generations \ -H "Authorization: Bearer $RIFFADS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "capability_id": "actor_ultra", "config": { "script": "Two weeks of battery, in a case this small." }, "actor_id": "act_0193c8f0a1b24e7f9d3c5a6b7e8f0011", "voice_id": "voc_0193c8f0a1b24e7f9d3c5a6b7e8f0022", "approved_voice_generation_id": "gen_0193c8f0a1b24e7f9d3c5a6b7e8f0033", "max_credits": 400 }' ``` The `max_credits` values are placeholders: send each step's `max_credits_needed` ([Price first](#price-first)). Waiting: [Wait for the result](#wait-for-the-result). Refused with `invalid_config`, before any hold: * No finished voice generation is named. Run the voice first and wait for it. * The script, actor or voice differ from the voice's. Send the same three to both calls. * `approved_voice_generation_id` is sent to Seedance 2.5 Actor (`actor_seedance`). Leave it out. ### Use your own recording [#use-your-own-recording] Have a voice file? Skip Text to Speech (`tts`). [Upload it](#bring-your-own-files), wait until it is usable, then send its id as `voice_audio`: ```json title="Submit body, before max_credits" { "capability_id": "actor_ultra", "config": { "voice_audio": ["ast_0193c8f0a1b24e7f9d3c5a6b7e8f0044"] }, "actor_id": "act_0193c8f0a1b24e7f9d3c5a6b7e8f0011" } ``` * Send no script and no `voice_id`. The recording sets the length, inside the actor's range above. * On MCP, use `submit_generation`: `generate_talking_actor` needs a script. ### One call [#one-call] Seedance 2.5 Actor (`actor_seedance`) speaks the script as part of the render. There is no voice step, no `voice_id` and no `approved_voice_generation_id`. ```json title="Submit body, before max_credits" { "capability_id": "actor_seedance", "config": { "script": "Two weeks of battery, in a case this small." }, "actor_id": "act_0193c8f0a1b24e7f9d3c5a6b7e8f0011" } ``` * The script sets the length, 4 to 30 seconds. A longer script is refused before any hold. * The voice changes every render: two ads from one actor sound like different people. ## Bring your own files [#bring-your-own-files] 1. **Reserve** with the file name, type and exact size. You get an `asset_id` and an `upload_url` that lasts 5 minutes. 2. **PUT the bytes** to `upload_url`, with no API key. 3. **Finalize.** Use the `ast_` id once the answer says `usable: true`. * Or import from a direct link to one media file (a web page is refused). * `riffads upload ` does all three steps. * Sizes and types: [Limits](/reference/limits). Fields: [Uploads](/api/uploads). Put the file in a slot field of `config`, then point at its alias in the prompt (`/image1`, `/video1`). Video models, image models and presets take a list of entries: ```json title="config: a start frame for Kling 3 Pro" { "prompt": "Slow push in, the bottle turns toward camera", "start_frame": [ { "assetId": "ast_0193c8f0a1b24e7f9d3c5a6b7e8f0061", "alias": "image1", "role": "start_frame" } ], "duration": 5 } ``` Every other file field (editing tools, voice tools, actor recordings, text jobs) takes plain ids, like `"voice_audio": ["ast_..."]`. The schema shows the form. ## One job at a time [#one-job-at-a-time] * One agent job runs at a time: per API key on REST and the CLI, per person on MCP. * A second submit gets `submission_in_flight` (409) with `in_flight.generation_id`. Wait on that job, then submit. * A `variants` submit is one job. Studio jobs do not count. A stuck job frees the slot after 10 minutes. * For parallel REST jobs, use a second API key. ## Refusals and retries [#refusals-and-retries] Every refusal has the same fields on every surface. | Field | What it is | | --------------------- | ------------------------------------------ | | `code` | The fixed reason. Branch on it | | `message` | One safe sentence. Show it, never parse it | | `retryable` | Whether you may resend the same call | | `retry_after_seconds` | Wait this long first (some codes only) | | `credits_charged` | What it cost, almost always `0` | * `retryable: false`: change the request or stop. `retryable: true`: at most two more tries. * `moderation_blocked` is final. Never reword a request to get past the check. * Lost the answer to a submit? List your generations first: a second submit is a second charge. Every code: [Errors](/reference/errors). ## Webhooks [#webhooks] A server can skip the wait loop: RiffAds POSTs a signed event when work settles. * Register an endpoint once per workspace (REST, CLI or the app). No request takes a webhook field, and MCP cannot register one. * Events: `generation.completed`, `generation.failed`, `batch.settled`, `workflow_run.completed`, `workflow_run.failed`, `credits.low`. * An event carries ids, never a link. Read the generation, then download. * Verify each delivery with the `webhook-id`, `webhook-timestamp` and `webhook-signature` headers: [Webhooks](/api/webhooks). ## Same job, every surface [#same-job-every-surface] | Job | MCP tool | CLI command | REST route | | -------------------------------------- | ------------------------------------------------------- | -------------------------------- | ----------------------------------------------------------------------- | | List models and tools | `list_capabilities` | `riffads capabilities` | `GET /capabilities` | | Read a schema | `get_capability_schema` | `riffads capabilities show ` | `GET /capabilities/{id}` | | Price a job | `estimate_generation` | `riffads estimate` | `POST /estimates` | | Start a job | `submit_generation` | `riffads generate` | `POST /generations` | | Talking actor ([how](#talking-actors)) | `generate_talking_actor` | `riffads generate --actor` | `POST /generations` | | Analyze an ad | `submit_generation` with Analyze Media (`analyze_media`) | `riffads analyze` | `POST /generations` | | Wait for a job | `wait_for_generation` | `riffads status --wait` | `GET /generations/{id}/wait` | | Read a job now | `get_generation` | `riffads status ` | `GET /generations/{id}` | | Read all takes | `get_batch` | `riffads batch ` | `GET /batches/{id}` | | List past jobs | `list_generations` | `riffads list` | `GET /generations` | | Get a fresh link | `get_asset` | `riffads download ` | `GET /assets/{id}/download` | | Search your files | `search_library` | `riffads search` | `GET /assets` | | Upload a file | `create_upload`, `finalize_upload` | `riffads upload ` | `POST /uploads`, `POST /uploads/{id}/finalize` | | Import from a link | `import_media_from_url` | `riffads upload --url` | `POST /uploads/from-url` | | Find actors | `list_actors` | `riffads actors` | `GET /actors` | | Find voices | `list_voices` | `riffads voices` | `GET /voices` | | Presets | `list_presets` | `riffads presets` | `GET /presets`, `GET /presets/{id}/templates` | | Workflow templates | `list_templates` | `riffads workflows templates` | `GET /workflows/templates` | | Run a workflow | `run_workflow` | `riffads workflows invoke` | `POST /workflows/templates/{key}/invoke`, `POST /workflows/{id}/invoke` | | Follow a run | `get_workflow_run` | `riffads workflows run ` | `GET /workflow-runs/{id}` | | List runs | `list_workflow_runs` | `riffads workflows runs` | `GET /workflow-runs` | | Credit balance | `get_credit_balance` | `riffads credits` | `GET /credits/balance` | | Check the connection | `riffads_ping` | `riffads whoami` | `GET /credits/balance` | | Webhooks | none | `riffads webhooks` | `GET /webhooks`, `POST /webhooks`, `DELETE /webhooks/{id}` | Every field and flag: [MCP tools](/mcp/tools), [CLI commands](/cli/commands), [Generations API](/api/generations).