curl -X POST "https://api.hooked.so/v1/project/create/podcast-interview" \
-H "x-api-key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"script": "[A] 8 out of 10 people say they struggle to make it to the end of the month. [/A]\n[B] Quick question. Do you consider yourself middle class? [/B]\n[A] [pauses, thinking] Hmm, I would say yes. [/A]\n[B] [camera] If you want to learn to save, comment SAVE below. [/camera] [/B]",
"avatarId": "cm4x9k2p10001ab12cd34ef56",
"guest": { "source": "generated", "description": "a man in his 30s, casual, average looking" },
"caption": { "preset": "tiktok" },
"webhook": "https://example.com/hooks/hooked?token=YOUR_SECRET"
}'
const response = await fetch("https://api.hooked.so/v1/project/create/podcast-interview", {
method: "POST",
headers: {
"x-api-key": "your_api_key_here",
"Content-Type": "application/json",
},
body: JSON.stringify({
mode: "dualcast",
script:
"[A] I look at myself in the mirror in these leggings and go: I look good. [/A]\n" +
"[B] They lift you and cinch your waist, it is next level. [/B]\n" +
"[A] I am leaving a photo up here [product] so you can see them. [/product] [/A]\n" +
"[B] The link is down below. [they both wave goodbye] [/B]",
dualcastAvatars: { left: "cm4x9k2p10001ab12cd34ef56", right: "cm4x9k2p10002ab12cd34ef56" },
dualcastSet: "a bright living room with plants",
productImageKey: "https://example.com/leggings.jpg",
webhook: "https://example.com/hooks/hooked?token=YOUR_SECRET",
}),
});
const result = await response.json();
console.log(result.data.projectId);
import requests
response = requests.post(
"https://api.hooked.so/v1/project/create/podcast-interview",
headers={"x-api-key": "your_api_key_here"},
json={
"script": (
"[A] 8 out of 10 people say they struggle to make it to the end of the month. [/A]\n"
"[B] Quick question. Do you consider yourself middle class? [/B]\n"
"[A] Hmm, I would say yes. [/A]"
),
"avatarId": "cm4x9k2p10001ab12cd34ef56",
"guest": {"source": "avatar", "avatarId": "cm4x9k2p10002ab12cd34ef56"},
"accent": "uk-london",
"webhook": "https://example.com/hooks/hooked?token=YOUR_SECRET",
},
)
print(response.json()["data"]["projectId"])
{
"success": true,
"data": {
"projectId": "cm4xa1b2c0002ab12cd34ef56",
"status": "processing"
},
"message": "Podcast successfully created"
}
{
"success": false,
"message": "script: Write the dialogue with turns from both people: [A] … [/A] and [B] … [/B]"
}
{
"code": "not_authenticated",
"message": "Not authenticated",
"errorCode": "NOT_AUTHENTICATED",
"details": { "x-api-key": "Header not provided or API Key invalid" }
}
{
"success": false,
"code": "missing_credentials",
"errorCode": "MISSING_CREDENTIALS",
"missingProviders": ["openrouter", "gemini"],
"message": "Your team uses its own provider keys (BYOK) and these are missing or invalid: OpenRouter, Google AI (Gemini). Add them in Settings → AI keys."
}
{
"success": false,
"code": "subscription_required",
"errorCode": "SUBSCRIPTION_REQUIRED",
"message": "Your team generates with Hooked's keys, which are paid by your plan. Subscribe to keep generating."
}
{
"success": false,
"errorCode": "INSUFFICIENT_CREDITS",
"message": "Not enough credits for the podcast. Estimated: 308, Available: 120",
"creditsNeeded": 308,
"creditsAvailable": 120
}
{
"code": "entitlement_required",
"error": "entitlement_required",
"message": "This endpoint requires the \"app\" product.",
"product": "app"
}
Podcast / Dualcast
A two-person podcast conversation with AI avatars
curl -X POST "https://api.hooked.so/v1/project/create/podcast-interview" \
-H "x-api-key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"script": "[A] 8 out of 10 people say they struggle to make it to the end of the month. [/A]\n[B] Quick question. Do you consider yourself middle class? [/B]\n[A] [pauses, thinking] Hmm, I would say yes. [/A]\n[B] [camera] If you want to learn to save, comment SAVE below. [/camera] [/B]",
"avatarId": "cm4x9k2p10001ab12cd34ef56",
"guest": { "source": "generated", "description": "a man in his 30s, casual, average looking" },
"caption": { "preset": "tiktok" },
"webhook": "https://example.com/hooks/hooked?token=YOUR_SECRET"
}'
const response = await fetch("https://api.hooked.so/v1/project/create/podcast-interview", {
method: "POST",
headers: {
"x-api-key": "your_api_key_here",
"Content-Type": "application/json",
},
body: JSON.stringify({
mode: "dualcast",
script:
"[A] I look at myself in the mirror in these leggings and go: I look good. [/A]\n" +
"[B] They lift you and cinch your waist, it is next level. [/B]\n" +
"[A] I am leaving a photo up here [product] so you can see them. [/product] [/A]\n" +
"[B] The link is down below. [they both wave goodbye] [/B]",
dualcastAvatars: { left: "cm4x9k2p10001ab12cd34ef56", right: "cm4x9k2p10002ab12cd34ef56" },
dualcastSet: "a bright living room with plants",
productImageKey: "https://example.com/leggings.jpg",
webhook: "https://example.com/hooks/hooked?token=YOUR_SECRET",
}),
});
const result = await response.json();
console.log(result.data.projectId);
import requests
response = requests.post(
"https://api.hooked.so/v1/project/create/podcast-interview",
headers={"x-api-key": "your_api_key_here"},
json={
"script": (
"[A] 8 out of 10 people say they struggle to make it to the end of the month. [/A]\n"
"[B] Quick question. Do you consider yourself middle class? [/B]\n"
"[A] Hmm, I would say yes. [/A]"
),
"avatarId": "cm4x9k2p10001ab12cd34ef56",
"guest": {"source": "avatar", "avatarId": "cm4x9k2p10002ab12cd34ef56"},
"accent": "uk-london",
"webhook": "https://example.com/hooks/hooked?token=YOUR_SECRET",
},
)
print(response.json()["data"]["projectId"])
{
"success": true,
"data": {
"projectId": "cm4xa1b2c0002ab12cd34ef56",
"status": "processing"
},
"message": "Podcast successfully created"
}
{
"success": false,
"message": "script: Write the dialogue with turns from both people: [A] … [/A] and [B] … [/B]"
}
{
"code": "not_authenticated",
"message": "Not authenticated",
"errorCode": "NOT_AUTHENTICATED",
"details": { "x-api-key": "Header not provided or API Key invalid" }
}
{
"success": false,
"code": "missing_credentials",
"errorCode": "MISSING_CREDENTIALS",
"missingProviders": ["openrouter", "gemini"],
"message": "Your team uses its own provider keys (BYOK) and these are missing or invalid: OpenRouter, Google AI (Gemini). Add them in Settings → AI keys."
}
{
"success": false,
"code": "subscription_required",
"errorCode": "SUBSCRIPTION_REQUIRED",
"message": "Your team generates with Hooked's keys, which are paid by your plan. Subscribe to keep generating."
}
{
"success": false,
"errorCode": "INSUFFICIENT_CREDITS",
"message": "Not enough credits for the podcast. Estimated: 308, Available: 120",
"creditsNeeded": 308,
"creditsAvailable": 120
}
{
"code": "entitlement_required",
"error": "entitlement_required",
"message": "This endpoint requires the \"app\" product.",
"product": "app"
}
Overview
Two people talking, in one of two shapes:- Podcast (
mode: "podcast"): each person filmed on their own and cut back and forth. The host is one of your avatars; the guest is generated in the same room from a description, or is another avatar. - Dualcast (
mode: "dualcast"): both people in the same shot. In each clip one talks while the other listens.
POST https://api.hooked.so/v1/project/create/podcast-interview
| Mode | Who is in it | Fields read |
|---|---|---|
podcast | A: the avatar in avatarId. B: guest, generated from guest.description or another avatar (guest.avatarId) | avatarId, guest, hostSet |
dualcast | Both people in one image: dualcastImageKey, or two avatars side by side (dualcastAvatars, with dualcastSet), or an avatar whose image already shows both (dualcastAvatarId). If you send more than one, they are used in that order | the chosen source, guest.voice (B’s voice) |
hostVoice, accent, productImageKey, aspectRatio, language, caption, content, musicId apply to both modes.
Writing the dialogue
Wrap each turn in who says it:[A] … [/A] (the host, or the person on the left in dualcast) and [B] … [/B] (the guest, or the person on the right). Lines starting with A: / B: are read the same. Both people must speak. A long turn is split between sentences into several clips; the whole video can have up to 24 clips.
Inside a turn:
- an action in brackets, in your words (
[nods]): at the start it happens before speaking, in the middle while saying the words around it, at the end after the line [camera] … [/camera]marks words said to the camera instead of to the other person (a closing call to action, for instance)[product] … [/product]marks the words during which the product photo (productImageKey) is on screen; whoever is talking points up to it as it appears
curl -X POST "https://api.hooked.so/v1/project/create/podcast-interview" \
-H "x-api-key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"script": "[A] 8 out of 10 people say they struggle to make it to the end of the month. [/A]\n[B] Quick question. Do you consider yourself middle class? [/B]\n[A] [pauses, thinking] Hmm, I would say yes. [/A]\n[B] [camera] If you want to learn to save, comment SAVE below. [/camera] [/B]",
"avatarId": "cm4x9k2p10001ab12cd34ef56",
"guest": { "source": "generated", "description": "a man in his 30s, casual, average looking" },
"caption": { "preset": "tiktok" },
"webhook": "https://example.com/hooks/hooked?token=YOUR_SECRET"
}'
const response = await fetch("https://api.hooked.so/v1/project/create/podcast-interview", {
method: "POST",
headers: {
"x-api-key": "your_api_key_here",
"Content-Type": "application/json",
},
body: JSON.stringify({
mode: "dualcast",
script:
"[A] I look at myself in the mirror in these leggings and go: I look good. [/A]\n" +
"[B] They lift you and cinch your waist, it is next level. [/B]\n" +
"[A] I am leaving a photo up here [product] so you can see them. [/product] [/A]\n" +
"[B] The link is down below. [they both wave goodbye] [/B]",
dualcastAvatars: { left: "cm4x9k2p10001ab12cd34ef56", right: "cm4x9k2p10002ab12cd34ef56" },
dualcastSet: "a bright living room with plants",
productImageKey: "https://example.com/leggings.jpg",
webhook: "https://example.com/hooks/hooked?token=YOUR_SECRET",
}),
});
const result = await response.json();
console.log(result.data.projectId);
import requests
response = requests.post(
"https://api.hooked.so/v1/project/create/podcast-interview",
headers={"x-api-key": "your_api_key_here"},
json={
"script": (
"[A] 8 out of 10 people say they struggle to make it to the end of the month. [/A]\n"
"[B] Quick question. Do you consider yourself middle class? [/B]\n"
"[A] Hmm, I would say yes. [/A]"
),
"avatarId": "cm4x9k2p10001ab12cd34ef56",
"guest": {"source": "avatar", "avatarId": "cm4x9k2p10002ab12cd34ef56"},
"accent": "uk-london",
"webhook": "https://example.com/hooks/hooked?token=YOUR_SECRET",
},
)
print(response.json()["data"]["projectId"])
{
"success": true,
"data": {
"projectId": "cm4xa1b2c0002ab12cd34ef56",
"status": "processing"
},
"message": "Podcast successfully created"
}
{
"success": false,
"message": "script: Write the dialogue with turns from both people: [A] … [/A] and [B] … [/B]"
}
{
"code": "not_authenticated",
"message": "Not authenticated",
"errorCode": "NOT_AUTHENTICATED",
"details": { "x-api-key": "Header not provided or API Key invalid" }
}
{
"success": false,
"code": "missing_credentials",
"errorCode": "MISSING_CREDENTIALS",
"missingProviders": ["openrouter", "gemini"],
"message": "Your team uses its own provider keys (BYOK) and these are missing or invalid: OpenRouter, Google AI (Gemini). Add them in Settings → AI keys."
}
{
"success": false,
"code": "subscription_required",
"errorCode": "SUBSCRIPTION_REQUIRED",
"message": "Your team generates with Hooked's keys, which are paid by your plan. Subscribe to keep generating."
}
{
"success": false,
"errorCode": "INSUFFICIENT_CREDITS",
"message": "Not enough credits for the podcast. Estimated: 308, Available: 120",
"creditsNeeded": 308,
"creditsAvailable": 120
}
{
"code": "entitlement_required",
"error": "entitlement_required",
"message": "This endpoint requires the \"app\" product.",
"product": "app"
}
What happens next
The stills of both people are prepared, one clip is generated per turn, and the clips are cut together and rendered. Either:- poll
GET /v1/project/{projectId}untildata.videois present anddata.video.statusisCOMPLETED, then downloaddata.video.url(the project’s ownstatusturnscompletedwhen the clips are assembled, a little before the render finishes); or - pass
webhookand wait for theCOMPLETED(orFAILED) call described in Webhooks:
{
"status": "COMPLETED",
"message": "Video completed",
"data": {
"videoId": "cm4xb7d8e0003ab12cd34ef56",
"projectId": "cm4xa1b2c0002ab12cd34ef56",
"status": "COMPLETED",
"url": "https://..."
}
}
Credits and your own keys
- Managed teams (Hooked’s provider keys) pay in credits: 100 credits per started 15 seconds of clips (every turn is its own clip, so a short answer still takes a whole clip), plus the images the pipeline generates: in podcast mode the host’s still turned towards the guest, one more with
hostSet, and the guest (one image when generated, two when it is an avatar placed in the room); in dualcast one image withdualcastAvatars, none from your own image. The estimate is charged when the project is created and refunded automatically if the project fails. - Teams on their own provider keys (BYOK) are not charged credits. They need an OpenRouter key and a Google AI (Gemini) key (the talking clips) in Settings → AI keys. Without them the request answers
402 missing_credentialsbefore anything is created or charged.
Errors
| Status | Code / message | What to do |
|---|---|---|
| 400 | script: Write the dialogue with turns from both people: …, script: Too long for one video (… clips, max 24) | Fix the dialogue. |
| 400 | avatarId: Avatar "…" not found., guest: The podcast needs a guest, guest.description: Describe the guest to generate them, guest.avatarId: Avatar "…" not found. | Podcast mode: send a valid host and guest. |
| 400 | dualcastImageKey: The image with both people (or dualcastAvatarId, or dualcastAvatars) is required for the dualcast mode, dualcastImageKey: The image must show exactly two people (it shows …), dualcastImageKey: The image does not belong to this team, dualcastAvatars.left: Avatar "…" not found. | Dualcast mode: send a valid source for the two people. |
| 400 | productImageKey: The image does not belong to this team | Use a key from your own library or an https URL. |
| 400 | caption.preset: Invalid caption preset "…", musicId: Music "…" not found., webhook: Must be a valid HTTPS URL, other <field>: <reason> | Fix the field named in the message. |
| 400 | Invalid JSON body | Send a valid JSON body. |
| 400 | Subscription not found | The team has no plan record. Contact support. |
| 401 | not_authenticated | Send a valid key in x-api-key. |
| 402 | missing_credentials | BYOK team: add the keys in missingProviders in Settings → AI keys. |
| 402 | subscription_required | Managed team without an active plan: subscribe. |
| 402 | INSUFFICIENT_CREDITS | Buy credits or wait for your plan to renew. creditsNeeded and creditsAvailable show the gap. |
| 403 | entitlement_required | The team does not have the Hooked app product. |
| 500 | Internal server error, Failed to create the podcast | Check your projects or your webhook before trying again. Credits charged are refunded. |
Idempotency-Key header to retry safely: if a request times out or answers 5xx, sending it again with the same key and body returns the first answer instead of creating (and charging) the project twice.Related
Project details
Webhooks
List Avatars
Talking Avatar
Headers
Makes the request safe to retry. 1-255 printable ASCII characters, one per operation (your job id, or a UUID you store), reused on every retry. Within 24 hours the same key with the same body answers with the first response and the header Idempotent-Replayed: true, without running or charging again. Keys are scoped to your team and the endpoint. 5xx answers and refusals before anything ran (401, 402, 403, 409, 429) are not kept. See Idempotency.
1 - 255^[\x20-\x7E]+$Query Parameters
true: only answer the price of this exact request, as { success: true, data: { dryRun: true, estimatedCredits } } with status 200. The request is validated like a real one (a 400 or 402 says the same), but nothing is created, queued or charged. estimatedCredits is exactly what the call without dryRun charges a managed team; a byok team is charged nothing. Do not send an Idempotency-Key with it.
Body
The dialogue. Wrap each turn in who says it: [A] … [/A] (the host, or the person on the left in dualcast) and [B] … [/B] (the guest, or the person on the right); lines starting with A: / B: read the same. Both people must speak. Every turn is its own clip and a long turn is split between sentences; at most 24 clips. Inside a turn: an action in brackets in your words ([nods]) happens before speaking at the start, or after the words before it; [camera] … [/camera] marks words said to the camera; [product] … [/product] marks the words during which productImageKey is on screen.
1 - 10000One accent card for both people. It applies only when it speaks the video's language (the first seven are English, the rest Spanish); unset or mismatched, the neutral accent of that language is used.
us-neutral-general-american, us-southern, us-new-york, uk-london, uk-northern-manchester, australian-neutral, irish-dublin, spanish-neutral-latin-american, spanish-spain-neutral-peninsular, spanish-mexico, spanish-colombia, spanish-argentina-rioplatense, spanish-caribbean HTTPS URL on a public host, called when the video is ready or the project fails (max 500 characters). Requests are signed: verify the Hooked-Signature header (HMAC-SHA256 of ".") with the signing secret from Settings → Webhooks; Hooked-Event and Hooked-Delivery headers name the event and the delivery. No redirects are followed; 10 s timeout; 3 immediate attempts. See the Webhooks guide for the payload.
500