Capabilities

Every thing RiffAds can make, by capability_id. Send that id to REST, MCP or the CLI. Same id, same fields everywhere.

This page is the map. The live list for your workspace is the truth: read it with GET /capabilities, list_capabilities (MCP) or riffads capabilities (CLI).

Read the live list first

curl -s https://app.riffads.com/api/v1/capabilities \
  -H "Authorization: Bearer $RIFFADS_API_KEY"

# one capability: its config_schema plus a valid example_config
curl -s https://app.riffads.com/api/v1/capabilities/veo_31 \
  -H "Authorization: Bearer $RIFFADS_API_KEY"

• capability_id is a plain string, not an enum. New ids appear with no deploy. Don't hardcode the list.
• category is avatar, video, image, tool or preset.
• output_kind is image, video, audio or text. Category is not output: auto_caption is a tool that outputs video.
• Media slots take asset ids (ast_ plus 32 hex chars) from uploads, always as an array, even for one file.
• Every capability ends in a signed file link (or text). Nothing posts anywhere.

Talking actor

actor_ultra: an actor speaks your script. Category avatar, output video.

• actor_id (or actor_image_asset_id), voice_id and approved_voice_generation_id are top-level submit fields, not config keys.
• Script road: run tts first, wait, then actor_ultra with approved_voice_generation_id. Recording road: fill voice_audio, no tts needed.
• No aspect_ratio: refused. Shape follows the actor image.
• No variants: refused. No captions switch: run auto_caption after.
• The id is actor_ultra. talking_actor is not an id.

Full flow: Talking actor ads.

Video models

One prompt, one generation, one video.

All take prompt (required, 8000 chars, Kling 3: 2500), count and prompt_enhancer (off by default).

Slot rules, checked before anything runs:

• end_frame needs start_frame: Kling V3, Kling 3, Seedance 1.5 Pro, H3 Max.
• Veo 3.1: no references mixed with frames. A start frame alone is refused: send both.
• Omni Flash: references or a source video, not both.
• Seedance 2: max 12 reference files. Reference audio needs a reference image or video. Reference video 2 to 15 s combined. Reference audio max 15 s combined.
• Kling 3 elements: up to 4, max one with a video, needs a start frame.
• A start frame or reference can narrow valid aspect_ratio, resolution and duration. The schema enums show the union. The estimate endpoint checks the exact config.

Image models

• image_size or aspect_ratio, never both. The schema says which.
• Up to 4 outputs per request over the API. GPT Image 2 publishes count up to 10: anything above 4 is clamped to 4 with a message.
• Seedream 4.5 with references: output count is clamped to the number of references.

Audio and text

Editing and media tools

Start from a file, not a prompt. One generation, one output, except split_scenes.

In-house tools take input files up to 500 MB. An input over a limit is refused before anything runs.

Tool settings

stitch, merge_layers, extract_audio, upscale, remove_background and skin_enhance have no settings beyond their files.

Chain tools by feeding one output's asset id into the next input slot.

Presets

Pick a template, add one file. Several steps run behind it.

Presets use the preset_ prefix and can launch with no deploy. The live list is the only full inventory.

Variants

Send top-level variants on submit to get N takes of one config.

• Max 4. Maps to the capability's count field and wins over a count inside config.
• No count field on the capability (talking actor included): variants is refused.
• The response has generation_ids and a batch_group_id. Read all takes with GET /batches/{batch_group_id} or get_batch. Watch every id, not just the first.

Refusals for an id

None are retryable. Re-read the list and pick an available row. All codes: Errors.