Skip to main content
POST

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.
You write the dialogue. Every turn becomes a clip of the person who says it. Voice, lip movement and gestures come from the video model; each person keeps the same voice in every clip, and both share one accent.
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


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} until data.video is present and data.video.status is COMPLETED, then download data.video.url (the project’s own status turns completed when the clips are assembled, a little before the render finishes); or
  • pass webhook and wait for the COMPLETED (or FAILED) call described in Webhooks:

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 with dualcastAvatars, 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_credentials before anything is created or charged.

Errors

Send an 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.

Project details

Follow the project until its video is ready

Webhooks

Payloads and delivery rules

List Avatars

Hosts, guests and dualcast avatars

Talking Avatar

One avatar speaking your script

Authorizations

x-api-key
string
header
required

Headers

Idempotency-Key
string

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.

Required string length: 1 - 255
Pattern: ^[\x20-\x7E]+$

Query Parameters

dryRun
boolean
default:false

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

application/json
script
string
required

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.

Required string length: 1 - 10000
mode
enum<string>
default:podcast

podcast: each person filmed on their own and cut back and forth (needs avatarId and guest). dualcast: both people in one shot, one talks while the other listens (needs dualcastImageKey, dualcastAvatars or dualcastAvatarId).

Available options:
podcast,
dualcast
name
string

Project name (max 100 characters). Generated when omitted.

Maximum string length: 100
avatarId
string

Podcast mode, required there: the host (A), an avatar from /v1/avatar/list. One already on a podcast set works best, since the generated guest sits in the same room. Ignored in dualcast.

Maximum string length: 30
guest
object

Podcast mode, required there: the guest (B). In dualcast only voice is read, as the voice of the person on the right.

dualcastImageKey
string

Dualcast: an image with exactly two people, a public https URL or the storage key of an image in your team's library (another team's key: 400). A is on the left, B on the right. Used first when you send more than one source.

Maximum string length: 1000
dualcastAvatarId
string

Dualcast: an avatar whose image already shows both people (A left, B right). Used only when neither dualcastImageKey nor dualcastAvatars is sent.

Maximum string length: 30
dualcastAvatars
object

Dualcast: two avatar IDs put side by side on a set (one more generated image, priced); left is A, right is B. Used only when dualcastImageKey is not sent.

dualcastSet
string

Dualcast with dualcastAvatars only: the set they sit on, in your words (max 300 characters).

Maximum string length: 300
hostSet
string

Podcast mode only: move the host to this set first, in your words (max 300 characters), e.g. a cozy podcast studio with a boom microphone. Only the background changes (one more generated image, priced).

Maximum string length: 300
productImageKey
string

A product photo (the id of an image in your media library, or a public https URL imported into your library first), shown at the top of the video on the words marked [product] … [/product]. Only used when the script marks them.

Maximum string length: 1000
hostVoice
enum<string>

A's voice card. Unset: the one that fits the host (podcast) or the person on the left (dualcast).

Available options:
young-woman-25-30,
woman-mid-20s,
woman-mid-30s,
older-woman-50,
young-man-25-30,
man-mid-20s,
man-mid-30s,
older-man-50
accent
enum<string>

One 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.

Available options:
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
aspectRatio
enum<string>
default:ratio_9_16
Available options:
ratio_9_16,
ratio_16_9,
ratio_1_1
language
string

Language of the dialogue, detected from the script when omitted. 2-letter ISO 639-1 code, e.g. en, es.

caption
object

Burned-in captions.

content
object

Branding.

musicId
string

Background music ID from /v1/music/list. An unknown ID answers 400.

Maximum string length: 30
webhook
string<uri>

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.

Maximum string length: 500
metadata
object

Any JSON object of your own (max 5 KB). Sent back in the webhook payload. The key automationId is reserved for dashboard automations and is removed.

Response

Project created. Follow it with GET /v1/project/{projectId} or wait for the webhook.

success
enum<boolean>
required
Available options:
true
data
object
required
message
string
required