Skip to main content
POST

Overview

A transformation ad: the before and the after enter on the lines that name them, and the avatar points at them during the hook. Send your own photos as beforeImageKey and afterImageKey (both or neither); without them both states are generated from the avatar. Wrap the words in [before] … [/before] and [after] … [/after]. Your media, if any, plays as B-roll: full frame in short muted bursts (up to 3 seconds each) over the middle of the video, when it runs longer than 10 seconds. This is one of the five UGC Studio formats; each one has its own endpoint and reads only its own fields. The avatar’s voice, lip movement and gestures are generated with the picture.

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.

Credits and your own keys

  • Teams on Hooked’s keys (managed): 7 credits plus 100 credits per started 15 seconds of script (estimated at about 2.5 words per second), plus the before and after images when you do not send your own. Charged up front when the project is created; refunded if it fails.
  • Teams on their own keys (BYOK): no credits are charged. The team needs OpenRouter and Google AI (Gemini) in Settings → AI keys; without them the request answers 402 missing_credentials and nothing is created.

What happens next

The clips are generated, assembled and rendered automatically.
  • Poll Get Project with the 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; failed (or a FAILED video) means it will not finish.
  • Or pass a webhook and get the result when the render finishes. See Webhooks.

List Avatars

Pick the presenter

Get Project

Status of the project

Webhooks

Payloads and delivery

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]+$

Body

application/json
script
string
required

What the avatar says. Wrap the words for each state in [before] … [/before] and [after] … [/after]. Marks are never spoken; unmarked, the director decides.

Required string length: 1 - 10000
avatarId
string
required

Avatar ID from /v1/avatar/list (the library's or your team's own). An unknown ID answers 400.

Maximum string length: 30
name
string

Project name (max 100 characters). Generated from the script when omitted. Outside the voiceover format it may be replaced by the on-screen hook the director writes once the clips are planned.

Maximum string length: 100
beforeImageKey
string

Your own before photo: a public https image URL or the storage key of an image in your team's library (a key of another team answers 400). Send it with afterImageKey; with only one of the two both are ignored. Without them the before and after are generated from the avatar (priced).

Maximum string length: 1000
afterImageKey
string

Your own after photo. Send it with beforeImageKey.

Maximum string length: 1000
media
string[]

B-roll: media IDs from your team's library (max 50), shown full frame in short muted bursts (up to 3 s each) over the middle of the video, when it is longer than 10 s. Any ID not in your library answers 400. A media that is not COMPLETED yet (an import or upload in progress) answers 400 media: Media "<id>" is not ready (status PROCESSING).

Maximum array length: 50

Media ID from your library

adSettings
object

B-roll. Also accepted as projectSettings.ad.

videoStyle
object

How the avatar is filmed and how it speaks. Every field is optional.

aspectRatio
enum<string>
default:ratio_9_16

Shape of the video.

Available options:
ratio_9_16,
ratio_16_9,
ratio_1_1
language
string

Language the avatar speaks; 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