REST API

Capabilities

List what you can run, read the exact config schema for one capability, and list preset templates.

Read as Markdown

Read 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.

EndpointReturnsPages
GET /capabilitiesEvery capability this workspace can seeyes
GET /capabilities/{capability_id}One config schema, plus a small valid exampleno
GET /presetsEvery preset, each with its first 20 templatesyes
GET /presets/{id}/templatesOne preset's full template listno
  • Scope Read, which every key has. These calls cost no credits.
  • capability_id is 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
ParameterTypeDefaultNotes
limitpositive integer25Clamped to 1 to 50
cursorstringnoneThe previous next_cursor

There is no search or category filter.

Terminal
curl -s https://app.riffads.com/api/v1/capabilities \
  -H "Authorization: Bearer $RIFFADS_API_KEY"
Response: 200 (trimmed)
{
  "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_id A to Z. next_cursor is 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 from GET /presets.

Read one schema

GET/api/v1/capabilities/{capability_id}API key
Terminal
curl -s https://app.riffads.com/api/v1/capabilities/actor_ultra \
  -H "Authorization: Bearer $RIFFADS_API_KEY"
Response: 200 (descriptions trimmed)
{
  "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 config is 400 invalid_config: Conventions.
  • Locked preset fields are absent. They come from the template, not from you.
  • required lists only keys with no default. OmniHuman 1.5 has none, but the submit still needs a script or a voice_audio file.
  • example_config is the smallest valid config. Its file slots hold the placeholder ast_00000000000000000000000000000000: put in real ids from Uploads.
  • count is 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": true is 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.

ShapeUsed byEach item
Array of idsTools, such as the source_video slot of Add CaptionsAn id string, "ast_..."
Array of objectsImage and video models, such as the start_frame slot of Kling 3 ProAn object with assetId, alias and role, all three required
One file in a model's slot
{
  "assetId": "ast_0193c8f0a1b24e7f9d3c5a6b7e8f0011",
  "alias": "image1",
  "role": "start_frame"
}
  • alias matches ^(image|video|audio)[1-9]\d*$. A prompt points at it as /image1.
  • role is fixed per slot: the schema gives it as a const, like "start_frame" or "reference".
  • maxItems on 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, resolution and duration, so test the config with POST /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_statuscodeHTTPMeaning
coming_sooncapability_unavailable404Listed, not live yet
retiredcapability_unavailable404Withdrawn. Old generations still read fine
requires_planrequired_plan403Your plan doesn't include it. Carries required_plan
unknowncapability_unavailable404Never 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 /estimates and POST /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
ParameterTypeDefaultNotes
limitinteger25Clamped to 1 to 50
cursorstringnoneThe previous next_cursor, sent back exactly
Terminal
curl -s https://app.riffads.com/api/v1/presets \
  -H "Authorization: Bearer $RIFFADS_API_KEY"
Response: 200 (trimmed)
{
  "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 fieldNotes
capability_idpreset_ id. Send it to estimate and submit
nameDisplay name. Never match on it
descriptionLeft out when empty
output_kindimage, video, audio or text
statusavailable, requires_plan or coming_soon. Only available can run
required_planOnly with requires_plan
requires_templatetrue: config.template_id is required
templatesThe first 20 live templates, in gallery order
templates_totalAll live templates. More than templates.length means the row is capped
next_actionHow to run it, written for an agent. Advice only
Template fieldNotes
template_idcaptpl_ id. The value for config.template_id
nameDisplay name
description, categoryCan be null. category is a gallery group, for display only
preview_urlA permanent public preview of RiffAds template art. It does not expire
preview_kindvideo or image: what preview_url holds
  • Order and cursor work like GET /capabilities. The body also has total, the presets this workspace can see.
  • requires_template: true with templates_total: 0 means the preset can't run right now. Its next_action says 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.

Terminal
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 with requires_plan), requires_template, templates and next_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:

CauseCodeHTTPRetryable
template_id missing on a preset that needs oneinvalid_config400no
template_id is not one of this preset's templatesnot_found404no
The template was withdrawn since you listed itcapability_unavailable404no
The preset needs a higher planrequired_plan403no
  • 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.

On this page