Capabilities
List what you can run, read the exact config schema for one capability, and list preset templates.
Read as MarkdownRead these before you submit: what you can run, what its config must look like, and which templates a preset takes. Which talking actor to pick: Talking actors.
| Endpoint | Returns | Pages |
|---|---|---|
GET /capabilities | Every capability this workspace can see | yes |
GET /capabilities/{capability_id} | One config schema, plus a small valid example | no |
GET /presets | Every preset, each with its first 20 templates | yes |
GET /presets/{id}/templates | One preset's full template list | no |
- Scope Read, which every key has. These calls cost no credits.
capability_idis a free string, never an enum. Read the list, don't hardcode it.- Paging: The list rule. Rates: Limits.
List capabilities
GET/api/v1/capabilitiesAPI key
| Parameter | Type | Default | Notes |
|---|---|---|---|
limit | positive integer | 25 | Clamped to 1 to 50 |
cursor | string | none | The previous next_cursor |
There is no search or category filter.
curl -s https://app.riffads.com/api/v1/capabilities \
-H "Authorization: Bearer $RIFFADS_API_KEY"{
"ok": true,
"capabilities": [
{
"capability_id": "actor_h3_max",
"name": "MiniMax H3 Max Lip Sync",
"description": "Sharper lip sync. Up to 14.8s of audio, and no direction.",
"category": "avatar",
"output_kind": "video",
"status": "available"
},
{
"capability_id": "actor_ultra",
"name": "OmniHuman 1.5",
"description": "Up to 60s of audio, and the only actor that takes a direction.",
"category": "avatar",
"output_kind": "video",
"status": "available"
},
{
"capability_id": "kling_3_pro",
"name": "Kling 3 Pro",
"description": "Kling 3 Pro: video with native audio, from a prompt or a start frame.",
"category": "video",
"output_kind": "video",
"status": "available"
},
{
"capability_id": "nb_pro",
"name": "Nano Banana Pro",
"description": "Gemini 3 Pro Image: the premium hero shot, up to 4K, best-in-class text rendering.",
"category": "image",
"output_kind": "image",
"status": "available"
}
],
"next_cursor": "auto_caption"
}The full body also has total: every row this workspace sees, retired ones left out.
Prop
Type
- Order: category (avatar, video, image, preset, tool), then
capability_idA to Z.next_cursoris the last row's id. - Hidden: retired rows and rows not offered to agents. Ask for one by id and the error says why.
- It changes without notice, with plans, launches and retirements. Read it each session.
- Not in the app's composer: Seedance 2.5 Actor, AI Writer and Analyze Media. Agents can still run them.
- Text results: AI Writer, Transcribe and Analyze Media return text in
output_text: Generations. - Presets are listed here too, with a
preset_id. Their templates come fromGET /presets.
Read one schema
GET/api/v1/capabilities/{capability_id}API key
curl -s https://app.riffads.com/api/v1/capabilities/actor_ultra \
-H "Authorization: Bearer $RIFFADS_API_KEY"{
"ok": true,
"capability": {
"capability_id": "actor_ultra",
"name": "OmniHuman 1.5",
"description": "Up to 60s of audio, and the only actor that takes a direction.",
"category": "avatar",
"output_kind": "video",
"config_schema": {
"type": "object",
"properties": {
"script": {
"description": "Script.",
"type": "string",
"maxLength": 1500
},
"voiceId": {
"description": "Voice. A voice id from list_voices.",
"type": "string",
"minLength": 1
},
"voice_audio": {
"description": "Audio. Upload a voice recording to use instead of a script. Up to 60s ...",
"maxItems": 1,
"type": "array",
"items": {
"type": "string",
"pattern": "^ast_[0-9a-f]{32}$"
}
},
"resolution": {
"default": "720p",
"description": "Resolution.",
"type": "string",
"enum": ["720p"]
}
},
"additionalProperties": false,
"description": "Configuration for OmniHuman 1.5. Only the keys listed here are accepted ..."
},
"example_config": {
"resolution": "720p"
}
}
}The detail has no status. A 200 means you can run it.
Schema rules
- Strict. An unknown key in
configis400 invalid_config: Conventions. - Locked preset fields are absent. They come from the template, not from you.
requiredlists only keys with no default. OmniHuman 1.5 has none, but the submit still needs ascriptor avoice_audiofile.example_configis the smallest valid config. Its file slots hold the placeholderast_00000000000000000000000000000000: put in real ids from Uploads.countis at most 4. What it gives back: Variants.- Read the descriptions. File limits, durations, step sizes and slot rules live there, and the MCP tools they name map to REST in Same job, every surface.
- A property marked
"deprecated": trueis an old name that still works for a while. Send the new name, never both: Deprecated properties.
File slots
A file slot takes one of two shapes. Config examples for both: Use the asset id.
| Shape | Used by | Each item |
|---|---|---|
| Array of ids | Tools, such as the source_video slot of Add Captions | An id string, "ast_..." |
| Array of objects | Image and video models, such as the start_frame slot of Kling 3 Pro | An object with assetId, alias and role, all three required |
{
"assetId": "ast_0193c8f0a1b24e7f9d3c5a6b7e8f0011",
"alias": "image1",
"role": "start_frame"
}aliasmatches^(image|video|audio)[1-9]\d*$. A prompt points at it as/image1.roleis fixed per slot: the schema gives it as aconst, like"start_frame"or"reference".maxItemson the slot is how many files it takes.
What the schema can't tell you
- Settings that depend on a file. A start frame can change the valid
aspect_ratio,resolutionandduration, so test the config withPOST /estimates. - The price. Get it from the free estimate: Price first.
Fields that are not config
actor_id, actor_image_asset_id, voice_id and approved_voice_generation_id go on the submit body. Inside config they are unknown keys: Generations.
Talking actors take no aspect_ratio. How to run one: The two-step flow.
Capability errors
An id you can't use adds capability_status next to code in the error body. None of these are retryable.
capability_status | code | HTTP | Meaning |
|---|---|---|---|
coming_soon | capability_unavailable | 404 | Listed, not live yet |
retired | capability_unavailable | 404 | Withdrawn. Old generations still read fine |
requires_plan | required_plan | 403 | Your plan doesn't include it. Carries required_plan |
unknown | capability_unavailable | 404 | Never existed, misspelled, or not offered to agents |
Read the list again and pick an available row. All codes: Errors.
Presets
A preset, such as Show Your App, is a capability whose id starts with preset_. These routes list its templates, the legal values for config.template_id.
- You price and run a preset with
POST /estimatesandPOST /generations, like any other capability. No preset route starts work. - What each preset makes, and an estimate body: Presets.
List presets
GET/api/v1/presetsAPI key
| Parameter | Type | Default | Notes |
|---|---|---|---|
limit | integer | 25 | Clamped to 1 to 50 |
cursor | string | none | The previous next_cursor, sent back exactly |
curl -s https://app.riffads.com/api/v1/presets \
-H "Authorization: Bearer $RIFFADS_API_KEY"{
"ok": true,
"presets": [
{
"capability_id": "preset_show_your_app",
"name": "Show Your App",
"description": "Put your app screenshot on a real person's phone, then bring it to life.",
"output_kind": "video",
"status": "available",
"requires_template": true,
"templates": [
{
"template_id": "captpl_0193c8f0a1b24e7f9d3c5a6b7e8f00a1",
"name": "Bedroom Selfie",
"description": "A creator shows her phone in a cosy fairy-lit bedroom.",
"category": "Bedroom",
"preview_url": "https://<public-preview-host>/templates/show-your-app/situation_app_01-preview.mp4",
"preview_kind": "video"
}
],
"templates_total": 1,
"next_action": "Call get_capability_schema with capability_id \"preset_show_your_app\" to see its other fields, then call submit_generation ... A preset is not a separate tool: submit_generation runs it like any other capability."
}
],
"next_cursor": null
}Names, counts and ids here are examples. Read the live list.
| Preset field | Notes |
|---|---|
capability_id | preset_ id. Send it to estimate and submit |
name | Display name. Never match on it |
description | Left out when empty |
output_kind | image, video, audio or text |
status | available, requires_plan or coming_soon. Only available can run |
required_plan | Only with requires_plan |
requires_template | true: config.template_id is required |
templates | The first 20 live templates, in gallery order |
templates_total | All live templates. More than templates.length means the row is capped |
next_action | How to run it, written for an agent. Advice only |
| Template field | Notes |
|---|---|
template_id | captpl_ id. The value for config.template_id |
name | Display name |
description, category | Can be null. category is a gallery group, for display only |
preview_url | A permanent public preview of RiffAds template art. It does not expire |
preview_kind | video or image: what preview_url holds |
- Order and cursor work like
GET /capabilities. The body also hastotal, the presets this workspace can see. requires_template: truewithtemplates_total: 0means the preset can't run right now. Itsnext_actionsays so.- A template id is a database id, not a slug. Read it fresh each time: an old id can be withdrawn.
One preset's templates
GET/api/v1/presets/{id}/templatesAPI key
The path id is a preset capability_id. You get every live template, with no cap and no paging.
curl -s https://app.riffads.com/api/v1/presets/preset_show_your_app/templates \
-H "Authorization: Bearer $RIFFADS_API_KEY"- The body has
capability_id,name,status,required_plan(only withrequires_plan),requires_template,templatesandnext_action. - Template fields are the same as in the list above.
- A capability that is not a preset (like Kling 3 Pro), a typo or a retired preset answers
404 not_found, with the message "No such preset. Call list_presets for the presets this workspace can use, or list_capabilities for everything else."
Preset refusals
On estimate and submit, the usual refusals apply. These ones are about presets:
| Cause | Code | HTTP | Retryable |
|---|---|---|---|
template_id missing on a preset that needs one | invalid_config | 400 | no |
template_id is not one of this preset's templates | not_found | 404 | no |
| The template was withdrawn since you listed it | capability_unavailable | 404 | no |
| The preset needs a higher plan | required_plan | 403 | no |
- On a template refusal, list the templates again and pick another.
- No preset authoring over the API, and no price per template. Price the full config with
POST /estimates.