curl -X POST "https://api.hooked.so/v1/project/create/scenes" \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product launch",
    "aspectRatio": "ratio_9_16",
    "scenes": [
      {
        "type": "avatar",
        "avatarId": "2",
        "script": "We just launched something you will love."
      },
      {
        "type": "video",
        "mediaId": "cm8w1r7d20001l708x9y8z7w6"
      },
      {
        "type": "picture_in_picture",
        "avatarId": "2",
        "mediaId": "cm8w1s0aa0002l708q1w2e3r4",
        "script": "And this is what it looks like in action."
      },
      {
        "type": "start_end_frame",
        "startFrameMediaId": "cm8w1t4bb0003l708t5y6u7i8",
        "endFrameMediaId": "cm8w1t9cc0004l708o9p0a1s2",
        "framePrompt": "The camera slowly pushes in on the product as the lights turn on",
        "frameDuration": 5,
        "frameModel": "veo_3_1"
      }
    ],
    "caption": { "preset": "modern", "alignment": "bottom" },
    "metadata": { "campaign": "launch-q4" }
  }'

const response = await fetch("https://api.hooked.so/v1/project/create/scenes", {
  method: "POST",
  headers: {
    "x-api-key": "your_api_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Product launch",
    // Two narrated clips
    scenes: [
      {
        type: "video",
        mediaId: "cm8w1r7d20001l708x9y8z7w6",
        script: "We just launched something you will love.",
        voiceId: "tzX5paJ07p5hyWFcU3uG",
      },
      {
        type: "video",
        mediaId: "cm8w1s0aa0002l708q1w2e3r4",
        script: "It takes thirty seconds to set up.",
        voiceId: "tzX5paJ07p5hyWFcU3uG",
      },
    ],
  }),
});

const { data } = await response.json();
console.log(data.projectId, data.status);

import requests

response = requests.post(
    "https://api.hooked.so/v1/project/create/scenes",
    headers={"x-api-key": "your_api_key_here"},
    json={
        "name": "Product launch",
        "scenes": [
            {"type": "avatar", "avatarId": "2",
             "script": "We just launched something you will love."},
            {"type": "picture_in_picture", "avatarId": "2",
             "mediaId": "cm8w1r7d20001l708x9y8z7w6",
             "script": "It takes thirty seconds to set up."},
        ],
    },
)
data = response.json()["data"]
print(data["projectId"], data["status"])

{
  "success": true,
  "data": {
    "projectId": "cm8x4f2qk0007l708a1b2c3d4",
    "status": "processing"
  },
  "message": "Scenes project successfully created"
}

{
  "success": false,
  "message": "scenes.1.mediaId: Media \"cm8w1r7d20001l708x9y8z7w6\" not found."
}

{
  "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", "bria"],
  "message": "Your team uses its own provider keys (BYOK) and these are missing or invalid: Google AI (Gemini), 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 scenes video. Estimated: 313, Available: 120",
  "creditsNeeded": 313,
  "creditsAvailable": 120
}

{
  "code": "entitlement_required",
  "error": "entitlement_required",
  "message": "This endpoint requires the \"app\" product.",
  "product": "app"
}