curl -X POST "https://api.hooked.so/v1/project/create/ugc-studio/before-after" \
-H "x-api-key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "Skin routine",
"script": "[before]Six weeks ago my skin looked like this.[/before] [after]This is it today.[/after] Here is what changed.",
"avatarId": "2",
"beforeImageKey": "https://example.com/images/before.png",
"afterImageKey": "https://example.com/images/after.png",
"language": "en",
"webhook": "https://example.com/hooks/hooked?token=YOUR_SECRET"
}'
const response = await fetch("https://api.hooked.so/v1/project/create/ugc-studio/before-after", {
method: "POST",
headers: {
"x-api-key": "your_api_key_here",
"Content-Type": "application/json",
},
body: JSON.stringify({
script: "My desk before and after one weekend of organising.",
avatarId: "2",
webhook: "https://example.com/hooks/hooked?token=YOUR_SECRET"
}),
});
const { data } = await response.json();
console.log(data.projectId, data.status);
import requests
response = requests.post(
"https://api.hooked.so/v1/project/create/ugc-studio/before-after",
headers={"x-api-key": "your_api_key_here"},
json={
"script": "Same room, one coat of paint later.",
"avatarId": "2",
"videoStyle": {
"cameras": [
"slow-orbit",
"static-shot"
]
},
"webhook": "https://example.com/hooks/hooked?token=YOUR_SECRET"
},
)
data = response.json()["data"]
print(data["projectId"], data["status"])
{
"success": true,
"data": {
"projectId": "cm8x4f2qk0007l708a1b2c3d4",
"status": "processing"
},
"message": "UGC ad successfully created"
}
{
"success": false,
"message": "script: Script must be at least 1 character"
}
{
"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": [["gemini"]],
"message": "Your team uses its own provider keys (BYOK) and these are missing or invalid: 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 UGC ad creation. Estimated: 107, Available: 40",
"creditsNeeded": 107,
"creditsAvailable": 40
}
{
"code": "entitlement_required",
"error": "entitlement_required",
"message": "This endpoint requires the \"app\" product.",
"product": "app"
}
Before / After
UGC Studio: a transformation ad, with the before and the after on the lines that name them
curl -X POST "https://api.hooked.so/v1/project/create/ugc-studio/before-after" \
-H "x-api-key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "Skin routine",
"script": "[before]Six weeks ago my skin looked like this.[/before] [after]This is it today.[/after] Here is what changed.",
"avatarId": "2",
"beforeImageKey": "https://example.com/images/before.png",
"afterImageKey": "https://example.com/images/after.png",
"language": "en",
"webhook": "https://example.com/hooks/hooked?token=YOUR_SECRET"
}'
const response = await fetch("https://api.hooked.so/v1/project/create/ugc-studio/before-after", {
method: "POST",
headers: {
"x-api-key": "your_api_key_here",
"Content-Type": "application/json",
},
body: JSON.stringify({
script: "My desk before and after one weekend of organising.",
avatarId: "2",
webhook: "https://example.com/hooks/hooked?token=YOUR_SECRET"
}),
});
const { data } = await response.json();
console.log(data.projectId, data.status);
import requests
response = requests.post(
"https://api.hooked.so/v1/project/create/ugc-studio/before-after",
headers={"x-api-key": "your_api_key_here"},
json={
"script": "Same room, one coat of paint later.",
"avatarId": "2",
"videoStyle": {
"cameras": [
"slow-orbit",
"static-shot"
]
},
"webhook": "https://example.com/hooks/hooked?token=YOUR_SECRET"
},
)
data = response.json()["data"]
print(data["projectId"], data["status"])
{
"success": true,
"data": {
"projectId": "cm8x4f2qk0007l708a1b2c3d4",
"status": "processing"
},
"message": "UGC ad successfully created"
}
{
"success": false,
"message": "script: Script must be at least 1 character"
}
{
"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": [["gemini"]],
"message": "Your team uses its own provider keys (BYOK) and these are missing or invalid: 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 UGC ad creation. Estimated: 107, Available: 40",
"creditsNeeded": 107,
"creditsAvailable": 40
}
{
"code": "entitlement_required",
"error": "entitlement_required",
"message": "This endpoint requires the \"app\" product.",
"product": "app"
}
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 asbeforeImageKey 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.
curl -X POST "https://api.hooked.so/v1/project/create/ugc-studio/before-after" \
-H "x-api-key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "Skin routine",
"script": "[before]Six weeks ago my skin looked like this.[/before] [after]This is it today.[/after] Here is what changed.",
"avatarId": "2",
"beforeImageKey": "https://example.com/images/before.png",
"afterImageKey": "https://example.com/images/after.png",
"language": "en",
"webhook": "https://example.com/hooks/hooked?token=YOUR_SECRET"
}'
const response = await fetch("https://api.hooked.so/v1/project/create/ugc-studio/before-after", {
method: "POST",
headers: {
"x-api-key": "your_api_key_here",
"Content-Type": "application/json",
},
body: JSON.stringify({
script: "My desk before and after one weekend of organising.",
avatarId: "2",
webhook: "https://example.com/hooks/hooked?token=YOUR_SECRET"
}),
});
const { data } = await response.json();
console.log(data.projectId, data.status);
import requests
response = requests.post(
"https://api.hooked.so/v1/project/create/ugc-studio/before-after",
headers={"x-api-key": "your_api_key_here"},
json={
"script": "Same room, one coat of paint later.",
"avatarId": "2",
"videoStyle": {
"cameras": [
"slow-orbit",
"static-shot"
]
},
"webhook": "https://example.com/hooks/hooked?token=YOUR_SECRET"
},
)
data = response.json()["data"]
print(data["projectId"], data["status"])
{
"success": true,
"data": {
"projectId": "cm8x4f2qk0007l708a1b2c3d4",
"status": "processing"
},
"message": "UGC ad successfully created"
}
{
"success": false,
"message": "script: Script must be at least 1 character"
}
{
"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": [["gemini"]],
"message": "Your team uses its own provider keys (BYOK) and these are missing or invalid: 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 UGC ad creation. Estimated: 107, Available: 40",
"creditsNeeded": 107,
"creditsAvailable": 40
}
{
"code": "entitlement_required",
"error": "entitlement_required",
"message": "This endpoint requires the \"app\" product.",
"product": "app"
}
Errors
| Status | Body | When |
|---|---|---|
| 400 | { success: false, message } | Invalid JSON body; Subscription not found (no plan record: contact support); a field fails validation (script: Script must be at least 1 character); a media ID not in your library; an unknown avatarId or musicId; an image key of another team; an invalid caption preset; webhook: Must be a valid HTTPS URL |
| 401 | not_authenticated | Missing or invalid x-api-key |
| 402 | missing_credentials | Your team uses its own keys (BYOK) and a key this request needs is missing. Nothing is created |
| 402 | subscription_required | Your team uses Hooked’s keys and has no active subscription |
| 402 | INSUFFICIENT_CREDITS | The estimate is higher than your balance |
| 403 | entitlement_required | Your team does not have the product this endpoint belongs to |
| 500 | { success: false, message } | Internal server error or Failed to create UGC ad. 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.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_credentialsand nothing is created.
What happens next
The clips are generated, assembled and rendered automatically.- Poll Get Project with the
projectIduntildata.videois present anddata.video.statusisCOMPLETED, then downloaddata.video.url. The project’s ownstatusturnscompletedwhen the clips are assembled, a little before the render finishes;failed(or aFAILEDvideo) means it will not finish. - Or pass a
webhookand get the result when the render finishes. See Webhooks.
Related
List Avatars
Get Project
Webhooks
Authorizations
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]+$Body
What the avatar says. Wrap the words for each state in [before] … [/before] and [after] … [/after]. Marks are never spoken; unmarked, the director decides.
1 - 10000Avatar ID from /v1/avatar/list (the library's or your team's own). An unknown ID answers 400.
30Project 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.
100Your 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).
1000Your own after photo. Send it with beforeImageKey.
1000B-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).
50Media ID from your library
B-roll. Also accepted as projectSettings.ad.
Show child attributes
Show child attributes
How the avatar is filmed and how it speaks. Every field is optional.
Show child attributes
Show child attributes
Shape of the video.
ratio_9_16, ratio_16_9, ratio_1_1 Language the avatar speaks; detected from the script when omitted. 2-letter ISO 639-1 code, e.g. en, es.
Burned-in captions.
Show child attributes
Show child attributes
Branding.
Show child attributes
Show child attributes
Background music ID from /v1/music/list. An unknown ID answers 400.
30HTTPS 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.
500Any 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.