curl -X POST "https://api.hooked.so/v1/character/create" \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Mia", "description": "Late 20s, red curly hair, denim jacket", "voiceProfile": "Warm, slightly husky, speaks fast", "generatePortrait": true }'

const response = await fetch("https://api.hooked.so/v1/character/create", {
  method: "POST",
  headers: { "x-api-key": process.env.HOOKED_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "Mia",
    description: "Late 20s, red curly hair, denim jacket",
    voiceProfile: "Warm, slightly husky, speaks fast",
    generatePortrait: true,
  }),
});
const { data: character } = await response.json();
// 202: poll GET /v1/character/{id} until imageStatus is COMPLETED
console.log(character.id, character.imageStatus);

import os
import requests

response = requests.post(
    "https://api.hooked.so/v1/character/create",
    headers={"x-api-key": os.environ["HOOKED_API_KEY"]},
    json={
        "name": "Mia",
        "description": "Late 20s, red curly hair, denim jacket",
        "voiceProfile": "Warm, slightly husky, speaks fast",
        "generatePortrait": True,
    },
)
character = response.json()["data"]
print(character["id"], character["imageStatus"])

{
  "success": true,
  "message": "Character created; its photo is processing",
  "data": {
    "id": "cm4xa1b2c0001cd34ef56gh78",
    "name": "Mia",
    "description": "Late 20s, red curly hair, denim jacket",
    "voiceProfile": "Warm, slightly husky, speaks fast",
    "presetId": "cinematic",
    "imageUrl": null,
    "imageStatus": "PROCESSING",
    "createdAt": "2026-09-30T18:00:00.000Z",
    "creditsCharged": 4
  }
}

{
  "success": false,
  "message": "description: Required to generate a portrait"
}