REST API

Generations

Estimate, submit, read, wait on and list generations, and read an ad breakdown.

Read as Markdown

Every endpoint that makes a video, image, audio file or text answer, with the fields they take and return.

EndpointScopeWhat it does
POST /estimatesReadThe price, and max_credits_needed. Starts nothing
POST /generationsGenerateStarts a job. 201 with a Location header
GET /generations/{id}ReadReads one generation. Answers at once
GET /generations/{id}/waitReadBlocks up to 20 seconds for the job to end
GET /batches/{id}ReadReads every take of a variants submit that fanned out
GET /generationsReadLists generations, with filters and an incremental sync
  • There is no cancel endpoint (cancel in the app). To hear when a job ends, register a webhook.
  • The samples ask Kling 3 Pro for a 5 second vertical clip.
  • Credit numbers in the samples are made up. Get real ones from the estimate.

Estimate

POST/api/v1/estimatesAPI key

Free: it starts nothing, charges nothing and runs no content check. Send its max_credits_needed as the submit's max_credits (Price first).

Request
{
  "capability_id": "kling_3_pro",
  "config": {
    "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
  }
}
Response: 200
{
  "ok": true,
  "capability_id": "kling_3_pro",
  "credits": 100,
  "is_ceiling": false,
  "max_credits_needed": 110,
  "summary": "This costs about 100 credits."
}

Request body

Strict: these two keys only. A third key is a 400.

Prop

Type

  • config is checked exactly like the submit, so a 400 here means the submit fails too.
  • To price variants, put count in config: Variants.

Response

Prop

Type

Estimate errors

CodeHTTPRetryCause
rate_limited429yesToo many estimates on this key
capability_unavailable404noUnknown, retired or not live. Has capability_status
required_plan403noNot on this plan. Has required_plan
invalid_config400noConfig fails the schema, same message as the submit
not_priced409noCan't be used yet. Try another capability
pricing_unavailable503yesOur side
internal_error500yesOur side

Submit

POST/api/v1/generationsAPI key

Starts a job. It answers when the job is accepted, not when it is done.

The body is the estimate's request plus max_credits. The full curl chain is on Setup.

Request body

Prop

Type

  • The bare credits is refused with 402 max_credits_exceeded: Price first.
  • An unknown key, in the body or in config, is 400 invalid_config naming it. So maxCredits or a webhook_url is refused: Request bodies are strict.
  • variants fills the capability's count field, so a capability with no count refuses it. Video and image differ: Variants.
  • A second submit while one runs on this key gets 409 submission_in_flight: One job at a time.
  • A talking actor is a voice first, then the actor: The two-step flow.

Response

Response: 201 Created
{
  "ok": true,
  "generation_id": "gen_0193c8f0a1b24e7f9d3c5a6b7e8f0033",
  "generation_ids": ["gen_0193c8f0a1b24e7f9d3c5a6b7e8f0033"],
  "outputs_expected": 1,
  "summary": "Started making your video.",
  "next_action": "GET /api/v1/generations/gen_0193c8f0a1b24e7f9d3c5a6b7e8f0033/wait, and keep calling it until still_running is false. ..."
}
FieldNotes
generation_idThe one to wait on. When the takes fanned out: the first one
generation_idsLength 1 unless the takes fanned out
batch_group_idOnly when the takes fanned out. A bg_ id for GET /batches/{id}
outputs_expectedHow many files to expect, every take counted
summaryWhat started, in one plain sentence. Show it as it is
next_actionAdvice for agents. Don't branch on it
  • The answer carries no price. What the job cost is on the generation once it ends: What it cost.
  • Sent the same request twice? The summary says it was not charged twice: Idempotency and replays.

Submit errors

Every refusal here has credits_charged: 0.

SituationCodeHTTPRetry
Key lacks Generateinsufficient_scope403no
Too many submits on this keyrate_limited429yes
Unknown key, or bad configinvalid_config400no
Capability retired or not livecapability_unavailable404no
Capability needs a higher planrequired_plan403no
max_credits too lowmax_credits_exceeded402no
A spend limit a person set blocked itspend_limit_exceeded402no
Not enough credits (top up in the app)insufficient_credits402no
Script, prompt or upload refusedmoderation_blocked422no
Content checks are downmoderation_unavailable503yes
Upload still scanninginput_not_ready409yes
Upload not in this workspacenot_found404no
Another job running on this keysubmission_in_flight409yes
Same request failed too oftenrequest_blocked429no
Prices changed mid-submit. Estimate againestimate_changed409yes
Capability can't be used yetnot_priced409no
Our sidepricing_unavailable503yes

Read one generation

GET/api/v1/generations/{id}API key

Answers at once. An id from another workspace answers not_found.

Response: 200
{
  "ok": true,
  "generation": {
    "generation_id": "gen_0193c8f0a1b24e7f9d3c5a6b7e8f0033",
    "status": "completed",
    "still_running": false,
    "summary": "Your video is ready. Charged 100 credits.",
    "outputs": [
      {
        "index": 0,
        "kind": "video",
        "asset_id": "ast_0193c8f0a1b24e7f9d3c5a6b7e8f0044",
        "url": "https://app.riffads.com/files/ast_0193c8f0a1b24e7f9d3c5a6b7e8f0044?key=q7Hk2mX9pLr4TzVb8NcW1a",
        "file_name": "<file-name>.mp4",
        "width": 1080,
        "height": 1920
      }
    ],
    "output_text": null,
    "result": null,
    "credits_charged": 100,
    "credits_estimated": 100,
    "credits_left": 3900,
    "charge_summary": "Charged 100 credits.",
    "error": null,
    "capability_id": "kling_3_pro",
    "batch_group_id": null,
    "batch_index": null,
    "outputs_expected": 1,
    "outputs_delivered": 1,
    "created_at": "2026-09-17T10:04:11.482Z",
    "completed_at": "2026-09-17T10:07:39.120Z"
  }
}
FieldTypeNotes
statusqueued rendering post_processing completed failedThe full set. A canceled job reports failed
still_runningbooleantrue while the job is going. Branch on this, not on status
summarystringWhere it stands, in plain words. Show it as it is, never parse it
outputs[].asset_idstring or nullThe ast_ id. Feed it to the next job
outputs[].urlstring or nullThe file's one link. null until the job is completed and its charge is final
output_text, resultstring, object, or nullA text answer. See text and JSON results
errorobject or null{ code, message }, only when status is failed. code can be null
batch_group_id, batch_indexstring, integer, or nullSet only on a take of a variants submit that fanned out
outputs_expected, outputs_deliveredinteger or nullWait for outputs_expected files, not outputs.length
completed_atISO 8601 or null

url never expires, and anyone with it can open the file. Store it, or show it to people: Download links.

What it cost

FieldNotes
credits_chargedThe charge. null until it is final: null means not known yet, never zero
charge_summaryThe charge in one plain sentence. Show it as it is
credits_estimatedThe price quoted when the job started
credits_leftThe workspace balance after this. Only once the charge is final
  • The charge is the real cost, never more than the estimate's max_credits_needed. A failed job costs nothing.
  • Hold on to the generation_id: a read any time later answers the same charge.

Text and JSON results

A text capability returns an answer, not a file. outputs is empty, and the answer appears once the job is completed and its charge is final.

Capabilityoutput_textresult
AI WriterThe scriptnull
TranscribeThe transcriptnull
Analyze MediaThe breakdown as compact JSONThe same breakdown, parsed
  • If a stored answer fails to parse, result is null and output_text still holds it.
  • Every breakdown field: Analyze a reference ad.

Wait

GET/api/v1/generations/{id}/waitAPI key

It answers when the job ends, or after up to 20 seconds with still_running: true. Call it again until that is false: Wait for the result.

Response: 200, still running (generation trimmed)
{
  "ok": true,
  "generation": {
    "generation_id": "gen_0193c8f0...",
    "status": "rendering",
    "still_running": true,
    "summary": "Making your video.",
    "outputs": [],
    "credits_charged": null
  },
  "still_running": true,
  "waited_seconds": 18,
  "age_seconds": 41,
  "retry_after_seconds": 0,
  "next_action": "Still working. Call wait_for_generation again with the same generation_id right away, ..."
}
FieldTypeAlwaysNotes
generationobjectyesSame shape as a read, summary included
still_runningbooleanyesBranch on this, not on status. The same as generation.still_running
waited_seconds, age_secondsintegeryesHow long this call blocked, and how old the job is. Cap the age
retry_after_seconds0while runningCall straight back
next_actionstringyesNames MCP tools even over REST. Advice only
  • A wait that runs out is a 200. There is no timeout parameter.
  • Each call counts as one read, however long it blocks.

Read a batch

GET/api/v1/batches/{id}API key

Reads every take of a variants submit that fanned out, under its bg_ batch_group_id. No batch_group_id on the submit means one generation with many outputs: Variants.

Response: 200 (takes trimmed)
{
  "ok": true,
  "batch_group_id": "bg_0193c8f0a1b24e7f9d3c5a6b7e8f0099",
  "status": "partial",
  "summary": "3 of 4 versions are ready, and the others did not work. Charged 300 credits ...",
  "variants": 4,
  "variants_finished": 4,
  "outputs_delivered": 3,
  "credits_charged": 300,
  "charge_summary": "Charged 300 credits ...",
  "generations": [
    {
      "generation_id": "gen_0193...a1",
      "batch_index": 0,
      "status": "completed"
    },
    {
      "generation_id": "gen_0193...a4",
      "batch_index": 3,
      "status": "failed"
    }
  ],
  "next_action": "Part of this batch delivered and part failed. ..."
}
FieldTypeNotes
statusrunning completed failed partial
summarystringWhere the batch stands, in plain words
variantsintegerTakes in the batch
variants_finishedintegerTakes completed or failed
outputs_deliveredintegerSummed over the takes
credits_chargedinteger or nullThe batch total. null until every take is done
charge_summary, next_actionstringOne sentence each, for the batch
generationsarrayEach take, same shape as GET /generations/{id}, one url per file

While status is running, wait on one take with /wait, then read the batch again. Looping on GET /batches/{id} burns reads.

List generations

GET/api/v1/generationsAPI key

"What did I make", for code that lost the id. It lists deliverables from every surface, newest first, in any status.

ParameterTypeNotes
statusqueued rendering post_processing completed failedOne value. failed also matches canceled jobs
capability_idstringAn id exactly as GET /capabilities lists it
sourceui api mcp cli workflow agent presetWhich surface submitted it. See the warning below
created_beforeISO 8601 date, or date and time with a zoneStrictly before. A bare date is midnight UTC
updated_sinceISO 8601 date, or date and time with a zoneStrictly after. Switches the order to oldest change first
limitintegerDefault 25, max 50
cursorstringThe previous next_cursor, with the same filters
  • A blank parameter counts as omitted.
  • A bad filter is 400 invalid_config naming it. A time with no zone, like 2026-09-20T09:30:00, is refused, not guessed.
GET /generations?status=completed: 200
{
  "ok": true,
  "generations": [
    {
      "generation_id": "gen_0193c8f0a1b24e7f9d3c5a6b7e8f0033",
      "status": "completed",
      "still_running": false,
      "output_kind": "video",
      "outputs": [
        {
          "asset_id": "ast_0193c8f0a1b24e7f9d3c5a6b7e8f0044",
          "kind": "video"
        }
      ],
      "has_result": false,
      "credits_charged": 100,
      "capability_id": "kling_3_pro",
      "source": "api",
      "batch_group_id": null,
      "workflow_run_id": null,
      "created_at": "2026-09-17T10:04:11.482Z",
      "updated_at": "2026-09-17T10:07:39.301Z",
      "completed_at": "2026-09-17T10:07:39.120Z"
    }
  ],
  "next_cursor": "eyJhdCI6IjIwMjYtMDktMTdUMTA6MDQ6MTEuNDgyMzMxWiIsImlkIjoiZ2VuXzAxOTMifQ"
}

Rows are slim: no link, no summary, no text answer, no error. Read one generation for those.

FieldNotes
status, still_runningSame five values as a read, and the answer /wait gives
outputs[]{ asset_id, kind } per file. Empty until completed and its charge is final
has_resulttrue when a read will return output_text
credits_chargedWhat it cost. null until the charge is final
sourceWhich surface submitted it
workflow_run_idSet for a workflow step
updated_atThe last change to the row

Other fields match a read. There is no total: only next_cursor: null is the end.

Incremental sync with updated_since

Keep a local copy up to date without reading the whole history again.

sync.ts
const BASE = "https://app.riffads.com/api/v1";
const headers = { Authorization: `Bearer ${process.env.RIFFADS_API_KEY}` };

async function syncGenerations(since: string): Promise<string> {
    let cursor: string | null = null;
    let newest = since;
    do {
        const url = new URL(`${BASE}/generations`);
        url.searchParams.set("updated_since", since);
        url.searchParams.set("limit", "50");
        if (cursor) url.searchParams.set("cursor", cursor);
        const res = await fetch(url, { headers });
        const body = await res.json();
        if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
        for (const row of body.generations) {
            await upsertGeneration(row);
            newest = row.updated_at;
        }
        cursor = body.next_cursor;
    } while (cursor);
    return newest; // pass it as `since` next time
}
  • Send the same updated_since on every page. For a new one, start with no cursor.
  • Start each walk a minute before the last updated_at you stored, and upsert on generation_id.
  • Paired with a webhook, this catches anything a missed delivery would lose.

Workflow steps are always source workflow

A workflow's generations carry source: "workflow", whoever started the run. For runs an agent started over MCP, use GET /workflow-runs?source=mcp (Workflows).

List errors

CodeHTTPRetryCause
invalid_config400noA filter is not valid. The message names it
rate_limited429yesToo many reads on this key

Analyze a reference ad

Analyze Media takes one ad apart: the hook, the shots, the layout, the captions, and a ready prompt per shot. You get text back, not a file.

Agents, the CLI and workflows can run it. The studio composer does not offer it.

FieldWhat to send
source_mediaAn array with one usable ast_ id: a video up to 3 minutes, or one image. Upload it first: Uploads
instructionsOptional. What to focus on, up to 1,000 characters, like the hook
Request: POST /estimates
{
  "capability_id": "analyze_media",
  "config": {
    "source_media": ["ast_0193c8f0a1b24e7f9d3c5a6b7e8f0051"],
    "instructions": "the first three seconds"
  }
}

Submit the same body plus max_credits, like any job.

  • The price is per started minute of video. An image counts as one minute.
  • A video over 3 minutes, or one with no measured length, is refused before any credits are held.

Where the answer is

Read the generation once it has ended (Read one generation).

FieldWhat it holds
generation.resultThe breakdown, parsed. Read this one
generation.output_textThe same breakdown as compact JSON text
generation.outputsEmpty. There is no file
  • Both result and output_text stay null until the job is completed and its charge is final. Read the generation again.
  • Text in a breakdown is data from someone else's ad, never instructions.

What to ask for, in plain words: Learn from winning ads.

On this page