curl "https://api.hooked.so/v1/character/list?limit=20" \
-H "x-api-key: your_api_key_here"
const response = await fetch("https://api.hooked.so/v1/character/list?limit=20", {
headers: { "x-api-key": process.env.HOOKED_API_KEY },
});
const { data } = await response.json();
const mia = data.characters.find((character) => character.name === "Mia");
import os
import requests
response = requests.get(
"https://api.hooked.so/v1/character/list",
params={"limit": 20},
headers={"x-api-key": os.environ["HOOKED_API_KEY"]},
)
characters = response.json()["data"]["characters"]
{
"success": true,
"message": "Characters fetched successfully",
"data": {
"characters": [
{
"id": "cm4xa1b2c0001cd34ef56gh78",
"name": "Mia",
"description": "Late 20s, red curly hair, denim jacket",
"voiceProfile": "Warm, slightly husky, speaks fast",
"presetId": "cinematic",
"imageUrl": "https://files.hooked.so/team/public/mia--fid--1a2b.png",
"imageStatus": "COMPLETED",
"createdAt": "2026-09-30T18:00:00.000Z"
}
],
"total": 1,
"limit": 50,
"offset": 0
}
}
Resources
List Characters
Your team’s Cinematic characters, the ids Create Cinematic Video takes in characterIds
GET
/
v1
/
character
/
list
curl "https://api.hooked.so/v1/character/list?limit=20" \
-H "x-api-key: your_api_key_here"
const response = await fetch("https://api.hooked.so/v1/character/list?limit=20", {
headers: { "x-api-key": process.env.HOOKED_API_KEY },
});
const { data } = await response.json();
const mia = data.characters.find((character) => character.name === "Mia");
import os
import requests
response = requests.get(
"https://api.hooked.so/v1/character/list",
params={"limit": 20},
headers={"x-api-key": os.environ["HOOKED_API_KEY"]},
)
characters = response.json()["data"]["characters"]
{
"success": true,
"message": "Characters fetched successfully",
"data": {
"characters": [
{
"id": "cm4xa1b2c0001cd34ef56gh78",
"name": "Mia",
"description": "Late 20s, red curly hair, denim jacket",
"voiceProfile": "Warm, slightly husky, speaks fast",
"presetId": "cinematic",
"imageUrl": "https://files.hooked.so/team/public/mia--fid--1a2b.png",
"imageStatus": "COMPLETED",
"createdAt": "2026-09-30T18:00:00.000Z"
}
],
"total": 1,
"limit": 50,
"offset": 0
}
}
Overview
Returns your team’s Cinematic characters, the ones under Studio → Characters in the dashboard, newest first. Pass a character’sid in characterIds of Create Cinematic Video (up to 6) and name it in the brief as @Name: it keeps its look, voice and photos.
imageUrl is the character’s reference photo as a signed URL that expires; it is null for a character without a photo (Cinematic draws a portrait for it) and while imageStatus is PROCESSING (a photo still being imported or generated, see Create Character). The list is paged with limit (default 50, at most 100) and offset; you are done when offset + limit >= total. Free and safe to retry.
curl "https://api.hooked.so/v1/character/list?limit=20" \
-H "x-api-key: your_api_key_here"
const response = await fetch("https://api.hooked.so/v1/character/list?limit=20", {
headers: { "x-api-key": process.env.HOOKED_API_KEY },
});
const { data } = await response.json();
const mia = data.characters.find((character) => character.name === "Mia");
import os
import requests
response = requests.get(
"https://api.hooked.so/v1/character/list",
params={"limit": 20},
headers={"x-api-key": os.environ["HOOKED_API_KEY"]},
)
characters = response.json()["data"]["characters"]
{
"success": true,
"message": "Characters fetched successfully",
"data": {
"characters": [
{
"id": "cm4xa1b2c0001cd34ef56gh78",
"name": "Mia",
"description": "Late 20s, red curly hair, denim jacket",
"voiceProfile": "Warm, slightly husky, speaks fast",
"presetId": "cinematic",
"imageUrl": "https://files.hooked.so/team/public/mia--fid--1a2b.png",
"imageStatus": "COMPLETED",
"createdAt": "2026-09-30T18:00:00.000Z"
}
],
"total": 1,
"limit": 50,
"offset": 0
}
}
Errors
| Status | When |
|---|---|
| 401 | Missing or invalid API key (code: "not_authenticated") |
| 403 | The team does not have the Hooked app product (code: "entitlement_required") |
Authorizations
Query Parameters
Page size, 1 to 100. Larger values are capped at 100; missing or invalid values fall back to 50.
Required range:
1 <= x <= 100Characters to skip. Missing or invalid values fall back to 0. You are done when offset + limit >= total.
Required range:
x >= 0