curl -X POST "https://api.hooked.so/v1/project/create/ugc-studio/fashion" \
-H "x-api-key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "Spring drop",
"script": "Three looks for spring. [look 1]This linen set is my favourite.[/look] [look 2]And this one for the weekend.[/look]",
"avatarId": "2",
"outfitImageKeys": [
"https://example.com/images/linen-set.png",
"https://example.com/images/weekend.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/fashion", {
method: "POST",
headers: {
"x-api-key": "your_api_key_here",
"Content-Type": "application/json",
},
body: JSON.stringify({
script: "Two outfits, one jacket. Here is how I style it.",
avatarId: "2",
outfitImageKeys: [
"https://example.com/images/jacket-casual.png",
"https://example.com/images/jacket-office.png"
],
adSettings: {
bRollType: "rounded-left"
},
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/fashion",
headers={"x-api-key": "your_api_key_here"},
json={
"script": "My new favourite dress, styled two ways.",
"avatarId": "2",
"media": [
"cm8w1r7d20002l708x9y8z7w7"
],
"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": "outfitImageKeys: Upload outfit photos (or your own outfit videos) for the fashion format"
}
{
"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": [["bria"]],
"message": "Your team uses its own provider keys (BYOK) and these are missing or invalid: Bria. 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"
}
Outfit / Fashion
UGC Studio: the avatar wears your outfits, one look per clip
curl -X POST "https://api.hooked.so/v1/project/create/ugc-studio/fashion" \
-H "x-api-key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "Spring drop",
"script": "Three looks for spring. [look 1]This linen set is my favourite.[/look] [look 2]And this one for the weekend.[/look]",
"avatarId": "2",
"outfitImageKeys": [
"https://example.com/images/linen-set.png",
"https://example.com/images/weekend.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/fashion", {
method: "POST",
headers: {
"x-api-key": "your_api_key_here",
"Content-Type": "application/json",
},
body: JSON.stringify({
script: "Two outfits, one jacket. Here is how I style it.",
avatarId: "2",
outfitImageKeys: [
"https://example.com/images/jacket-casual.png",
"https://example.com/images/jacket-office.png"
],
adSettings: {
bRollType: "rounded-left"
},
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/fashion",
headers={"x-api-key": "your_api_key_here"},
json={
"script": "My new favourite dress, styled two ways.",
"avatarId": "2",
"media": [
"cm8w1r7d20002l708x9y8z7w7"
],
"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": "outfitImageKeys: Upload outfit photos (or your own outfit videos) for the fashion format"
}
{
"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": [["bria"]],
"message": "Your team uses its own provider keys (BYOK) and these are missing or invalid: Bria. 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
The avatar wears your outfits, one look per clip. Send up to four outfit photos asoutfitImageKeys (each one is dressed on the avatar and filmed), or your own outfit videos as media, which then replace them; photos in media alone answer 400. Wrap the words for each look in [look 1] … [/look], [look 2] … [/look] and so on. The outfit and the avatar share the frame as adSettings says.
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/fashion" \
-H "x-api-key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "Spring drop",
"script": "Three looks for spring. [look 1]This linen set is my favourite.[/look] [look 2]And this one for the weekend.[/look]",
"avatarId": "2",
"outfitImageKeys": [
"https://example.com/images/linen-set.png",
"https://example.com/images/weekend.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/fashion", {
method: "POST",
headers: {
"x-api-key": "your_api_key_here",
"Content-Type": "application/json",
},
body: JSON.stringify({
script: "Two outfits, one jacket. Here is how I style it.",
avatarId: "2",
outfitImageKeys: [
"https://example.com/images/jacket-casual.png",
"https://example.com/images/jacket-office.png"
],
adSettings: {
bRollType: "rounded-left"
},
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/fashion",
headers={"x-api-key": "your_api_key_here"},
json={
"script": "My new favourite dress, styled two ways.",
"avatarId": "2",
"media": [
"cm8w1r7d20002l708x9y8z7w7"
],
"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": "outfitImageKeys: Upload outfit photos (or your own outfit videos) for the fashion format"
}
{
"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": [["bria"]],
"message": "Your team uses its own provider keys (BYOK) and these are missing or invalid: Bria. 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); no outfitImageKeys and no outfit video in media (outfitImageKeys: Upload outfit photos (or your own outfit videos) for the fashion format); 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 dressed image and the outfit video of each look made from a photo. 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, Google AI (Gemini) and Bria (Bria not when
adSettings.removeAvatarBackgroundisfalseoradSettings.avatarPresentationiscover) in Settings → AI keys; without them the request answers402 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
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
Up to 4 outfit photos, each the id of an image in your media library, or a public https image URL (imported into your library first; a stored key of your library still works). Each one is dressed on the avatar and filmed (priced per look). Needed unless you send outfit videos in media, which then replace them.
41000Your own outfit VIDEOS: media IDs from your team's library (max 50). Photos here are not read: send them as outfitImageKeys (photos in media alone answer 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
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