REST API

Library

Search your files, get a file's link, list actors and voices, and read the credit balance.

Read as Markdown

Read what the workspace already has: files, actors, voices and credits. You get ids back, then pass them into a submit.

EndpointReturnsPages
GET /assetsFiles in the library, with search and filtersyes
GET /assets/{id}One file's facts, and its linkno
GET /assets/{id}/downloadThe same link, and a name to save the file asno
GET /actorsActors this workspace may useyes
GET /voicesVoices this workspace may useyes
GET /credits/balanceThe balance, and the most one job may costno
  • Scope Read, which every key has. These calls cost no credits.
  • Paging works the same on every list: The list rule. Rates: Limits.

Files

Only finished, approved files appear: this workspace's uploads, imports and paid outputs. Anything else answers not_found, like an id that never existed.

Search the library

GET/api/v1/assetsAPI key
ParameterTypeDefaultNotes
qstringnoneSearches the file name and its generation's prompt and script. Case insensitive. Cut to 120 characters
kindimage video audionone
aspect_ratio9:16 16:9 1:1 4:5 4:3 3:4 2:3 3:2noneMatched within 2 percent of the real width and height
originupload generated url_importnoneHow the file got here
limitinteger25Clamped to 1 to 50
cursorstringnoneThe previous next_cursor, with the same filters

A bad kind, aspect_ratio or origin is 400 invalid_config, and the message lists the accepted values.

Terminal
curl -sG https://app.riffads.com/api/v1/assets \
  -H "Authorization: Bearer $RIFFADS_API_KEY" \
  --data-urlencode "q=bottle" \
  --data-urlencode "kind=video" \
  --data-urlencode "aspect_ratio=9:16"
Response: 200
{
  "ok": true,
  "assets": [
    {
      "asset_id": "ast_0193c8f0a1b24e7f9d3c5a6b7e8f0044",
      "kind": "video",
      "origin": "generated",
      "name": "Generation 0193c8f0",
      "mime_type": "video/mp4",
      "size_bytes": 8421377,
      "width": 1080,
      "height": 1920,
      "aspect_ratio": "9:16",
      "duration_ms": 8000,
      "created_at": "2026-09-17T10:07:39.120Z",
      "generation_id": "gen_0193c8f0a1b24e7f9d3c5a6b7e8f0033",
      "source_url": null
    }
  ],
  "next_cursor": null
}
FieldNotes
nameA label, not a filename
mime_typeCan be null
width, heightnull for audio or an unmeasured file
aspect_ratioThe matching shape from the filter list, or null
duration_msnull for images
generation_idThe generation that made it. null unless origin is generated
source_urlWhere an import came from, without its query string. null unless origin is url_import
  • Newest first. No total.
  • No row carries a link. Read one file for its url.

Read one file

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

Answers one asset object, with the same fields as a search row, and the file's link in url.

Response: 200 (asset trimmed)
{
  "ok": true,
  "asset": {
    "asset_id": "ast_0193c8f0a1b24e7f9d3c5a6b7e8f0044",
    "kind": "video",
    "origin": "generated",
    "aspect_ratio": "9:16",
    "duration_ms": 8000
  },
  "url": "https://app.riffads.com/files/ast_0193c8f0a1b24e7f9d3c5a6b7e8f0044?key=q7Hk2mX9pLr4TzVb8NcW1a"
}
  • url is the file's one link. It never expires, and anyone with it can open the file: Download links.
  • The link is the same on every read, so store it or hand it on.
GET/api/v1/assets/{id}/downloadAPI key

Answers JSON, never a redirect. Read url from the body, then GET it.

Terminal
URL=$(curl -s https://app.riffads.com/api/v1/assets/ast_0193c8f0a1b24e7f9d3c5a6b7e8f0044/download \
  -H "Authorization: Bearer $RIFFADS_API_KEY" | jq -r '.url')
curl -sL -o hook.mp4 "$URL"
Response: 200
{
  "ok": true,
  "asset_id": "ast_0193c8f0a1b24e7f9d3c5a6b7e8f0044",
  "url": "https://app.riffads.com/files/ast_0193c8f0a1b24e7f9d3c5a6b7e8f0044?key=q7Hk2mX9pLr4TzVb8NcW1a",
  "filename": "generation-0193c8f0.mp4"
}
  • url is the same permanent link a read carries. There is no second, shorter one.
  • GET it with no API key, and follow the redirect (curl -L).
  • Add download=1 to its query to make a browser save the file as filename instead of showing it.
  • Works for any file in the library, so an old output never needs a new render.
  • An output's asset_id goes straight into the next config's file slot. No download and upload again.
  • 404 not_found for another workspace's id, a bad id, a file still being checked, a refused or deleted file, and an output whose charge is not final yet.

Actors and voices

New actors, voices, brands and products are made in the app at app.riffads.com. REST only lists actors and voices.

Actors

GET/api/v1/actorsAPI key

The RiffAds cast plus the active actors your workspace made.

ParameterTypeDefaultNotes
searchstringnoneName or description, case insensitive
limitinteger25Clamped to 1 to 50. A page holds at most 48, so 49 and 50 return 48
cursorstringnoneThe previous next_cursor, sent back exactly

There is no gender, tag or age filter. Match gender, age_band and tags yourself.

Terminal
curl -sG https://app.riffads.com/api/v1/actors \
  -H "Authorization: Bearer $RIFFADS_API_KEY" \
  --data-urlencode "search=warm" \
  --data-urlencode "limit=50"
Response: 200
{
  "ok": true,
  "actors": [
    {
      "actor_id": "act_0193c8f0a1b24e7f9d3c5a6b7e8f0011",
      "name": "Maya",
      "description": "Warm, direct, speaks to camera at home",
      "gender": "female",
      "age_band": "adult",
      "tags": ["kitchen", "morning", "standing", "casual"],
      "default_voice_id": "voc_0193c8f0a1b24e7f9d3c5a6b7e8f0022",
      "default_voice_name": "Maya (natural)",
      "is_platform": true
    }
  ],
  "next_cursor": "eyJpc09yZyI6ZmFsc2UsImlzQ29yZSI6dHJ1ZX0"
}
FieldNotes
nameNot unique: match on the id
descriptionOne line of casting copy, matched by search. Can be null
genderfemale, male, nonbinary, or null
age_bandkid, young_adult, adult, senior, or null
tagssnake_case situation tags, like kitchen. Never null
default_voice_id, default_voice_nameThe voice this actor normally uses, or null
is_platformtrue for the RiffAds cast, false for your own
  • Order: your actors first, then the core cast, then the rest. Newest first in each group.
  • No total. Higher plans see more of the cast, and your own actors are always listed.
  • No face image or clip comes back. To see faces, open app.riffads.com.

Voices

GET/api/v1/voicesAPI key

The RiffAds voice library plus the voices your workspace cloned or designed. Active only, sorted by name.

ParameterTypeDefaultNotes
searchstringnoneName only, case insensitive
languagestringnoneAn exact tag, like en or es. Not a prefix
limitinteger25Clamped to 1 to 50
cursorstringnoneThe previous next_cursor, sent back exactly
Terminal
curl -sG https://app.riffads.com/api/v1/voices \
  -H "Authorization: Bearer $RIFFADS_API_KEY" \
  --data-urlencode "language=en"
Response: 200 (trimmed)
{
  "ok": true,
  "voices": [
    {
      "voice_id": "voc_0193c8f0a1b24e7f9d3c5a6b7e8f0022",
      "name": "Maya (natural)",
      "language": "en",
      "gender": "female",
      "tags": ["young_adult", "american", "conversational"],
      "is_cloned": false,
      "is_premium": false,
      "is_platform": true
    }
  ],
  "total": 1,
  "next_cursor": null
}
FieldNotes
nameThe only field search matches
languageA language tag, mostly ISO 639-1, or null
genderfemale, male, nonbinary, or null
tagssnake_case age, accent, energy and use tags. Never null
is_clonedtrue when cloned from a recording
is_premiumtrue for a voice RiffAds marks premium
is_platformtrue for the RiffAds library, false for your own
  • total counts the matches before paging. No preview audio comes back.
  • A cloned voice can have no language. A language filter misses it, so find it by name.
  • The voice cursor is an offset in a string. Send it back as is, never build one.

Use the ids in a submit

  • actor_id and voice_id go at the top level of the submit body, never in config: Generations.
  • voice_id is optional when the actor has a default_voice_id. Another workspace's id answers 404 not_found.
  • A talking actor is a voice first, then the actor: The two-step flow.

Credit balance

GET/api/v1/credits/balanceAPI key

What the workspace can spend now, and the most one generation from this key may cost. Read it before a big batch.

Terminal
curl -s https://app.riffads.com/api/v1/credits/balance \
  -H "Authorization: Bearer $RIFFADS_API_KEY"
Response: 200
{
  "ok": true,
  "credits_available": 4200,
  "most_one_generation_may_cost": 320,
  "summary": "You have 4,200 credits."
}
FieldNotes
credits_availableSpendable now. Credits promised to jobs still running are already taken out
most_one_generation_may_costThe most one job from this key may cost now: the smallest spend limit that applies to it. Quote this one to a person
summaryThe balance in one plain sentence
  • most_one_generation_may_cost leaves out the wallet. A job can still need more than credits_available.
  • A key with its own budget sees its own number here, not the workspace's.
  • Which limit binds shows up when one refuses a job, in limit.bound_by. The limits, their defaults and who sets them: Spend limits.
  • A failed read is 500 internal_error, retryable, and its message says it is not a balance problem. It never looks like an empty wallet.

Errors

CodeHTTPRetryableCause
invalid_config400noA library filter is not valid
not_found404noA file this workspace's agents can't see, for any reason
rate_limited429yesOver the agent_read rate. Carries Retry-After
internal_error500yesA file or the balance could not be read. Our side

Auth, plan and workspace codes: Errors.

On this page