Library
Search your files, get a file's link, list actors and voices, and read the credit balance.
Read as MarkdownRead what the workspace already has: files, actors, voices and credits. You get ids back, then pass them into a submit.
| Endpoint | Returns | Pages |
|---|---|---|
GET /assets | Files in the library, with search and filters | yes |
GET /assets/{id} | One file's facts, and its link | no |
GET /assets/{id}/download | The same link, and a name to save the file as | no |
GET /actors | Actors this workspace may use | yes |
GET /voices | Voices this workspace may use | yes |
GET /credits/balance | The balance, and the most one job may cost | no |
- 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
| Parameter | Type | Default | Notes |
|---|---|---|---|
q | string | none | Searches the file name and its generation's prompt and script. Case insensitive. Cut to 120 characters |
kind | image video audio | none | |
aspect_ratio | 9:16 16:9 1:1 4:5 4:3 3:4 2:3 3:2 | none | Matched within 2 percent of the real width and height |
origin | upload generated url_import | none | How the file got here |
limit | integer | 25 | Clamped to 1 to 50 |
cursor | string | none | The 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.
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"{
"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
}| Field | Notes |
|---|---|
name | A label, not a filename |
mime_type | Can be null |
width, height | null for audio or an unmeasured file |
aspect_ratio | The matching shape from the filter list, or null |
duration_ms | null for images |
generation_id | The generation that made it. null unless origin is generated |
source_url | Where 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.
{
"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"
}urlis 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 a download link
GET/api/v1/assets/{id}/downloadAPI key
Answers JSON, never a redirect. Read url from the body, then GET it.
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"{
"ok": true,
"asset_id": "ast_0193c8f0a1b24e7f9d3c5a6b7e8f0044",
"url": "https://app.riffads.com/files/ast_0193c8f0a1b24e7f9d3c5a6b7e8f0044?key=q7Hk2mX9pLr4TzVb8NcW1a",
"filename": "generation-0193c8f0.mp4"
}urlis 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=1to its query to make a browser save the file asfilenameinstead of showing it. - Works for any file in the library, so an old output never needs a new render.
- An output's
asset_idgoes straight into the next config's file slot. No download and upload again. 404 not_foundfor 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.
| Parameter | Type | Default | Notes |
|---|---|---|---|
search | string | none | Name or description, case insensitive |
limit | integer | 25 | Clamped to 1 to 50. A page holds at most 48, so 49 and 50 return 48 |
cursor | string | none | The previous next_cursor, sent back exactly |
There is no gender, tag or age filter. Match gender, age_band and tags yourself.
curl -sG https://app.riffads.com/api/v1/actors \
-H "Authorization: Bearer $RIFFADS_API_KEY" \
--data-urlencode "search=warm" \
--data-urlencode "limit=50"{
"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"
}| Field | Notes |
|---|---|
name | Not unique: match on the id |
description | One line of casting copy, matched by search. Can be null |
gender | female, male, nonbinary, or null |
age_band | kid, young_adult, adult, senior, or null |
tags | snake_case situation tags, like kitchen. Never null |
default_voice_id, default_voice_name | The voice this actor normally uses, or null |
is_platform | true 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.
| Parameter | Type | Default | Notes |
|---|---|---|---|
search | string | none | Name only, case insensitive |
language | string | none | An exact tag, like en or es. Not a prefix |
limit | integer | 25 | Clamped to 1 to 50 |
cursor | string | none | The previous next_cursor, sent back exactly |
curl -sG https://app.riffads.com/api/v1/voices \
-H "Authorization: Bearer $RIFFADS_API_KEY" \
--data-urlencode "language=en"{
"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
}| Field | Notes |
|---|---|
name | The only field search matches |
language | A language tag, mostly ISO 639-1, or null |
gender | female, male, nonbinary, or null |
tags | snake_case age, accent, energy and use tags. Never null |
is_cloned | true when cloned from a recording |
is_premium | true for a voice RiffAds marks premium |
is_platform | true for the RiffAds library, false for your own |
totalcounts the matches before paging. No preview audio comes back.- A cloned voice can have no language. A
languagefilter 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_idandvoice_idgo at the top level of the submit body, never inconfig: Generations.voice_idis optional when the actor has adefault_voice_id. Another workspace's id answers404 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.
curl -s https://app.riffads.com/api/v1/credits/balance \
-H "Authorization: Bearer $RIFFADS_API_KEY"{
"ok": true,
"credits_available": 4200,
"most_one_generation_may_cost": 320,
"summary": "You have 4,200 credits."
}| Field | Notes |
|---|---|
credits_available | Spendable now. Credits promised to jobs still running are already taken out |
most_one_generation_may_cost | The most one job from this key may cost now: the smallest spend limit that applies to it. Quote this one to a person |
summary | The balance in one plain sentence |
most_one_generation_may_costleaves out the wallet. A job can still need more thancredits_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
| Code | HTTP | Retryable | Cause |
|---|---|---|---|
invalid_config | 400 | no | A library filter is not valid |
not_found | 404 | no | A file this workspace's agents can't see, for any reason |
rate_limited | 429 | yes | Over the agent_read rate. Carries Retry-After |
internal_error | 500 | yes | A file or the balance could not be read. Our side |
Auth, plan and workspace codes: Errors.