> ## Documentation Index > Fetch the complete documentation index at: https://docs.hooked.so/llms.txt > Use this file to discover all available pages before exploring further. # Create Character > Save a Cinematic character, with a photo from your library, a URL or a generated portrait ## Overview Saves a character to your team, the same as **Studio → Characters → New character** in the dashboard. Pass its `id` in `characterIds` of [Create Cinematic Video](/api-reference/video/cinematic) to cast it. A character has a `name` (how the story calls it, up to 60 characters), a visual `description`, a `voiceProfile` (how it sounds, in words) and a `presetId` (the visual style of a generated portrait, `cinematic` by default; any id of the `visual-styles` [catalog](/api-reference/catalog/get) or your own `custom-`). Only `name` is required. ## The photo Send at most one of these. Without any, the character has no photo, and Cinematic draws a portrait for it when it is cast. | Field | What happens | Cost | | - | - | - | | `mediaId` | An image of your [media library](/api-reference/media/list), already `COMPLETED`, becomes the photo. | Free | | `imageUrl` | A public `https` JPEG, PNG, WEBP or GIF is imported into your library after the response (like [Import Media](/api-reference/media/import)). | Free, counts against your storage | | `generatePortrait: true` | A portrait is generated from `description` in the character's style, after the response. Pick the model with `imageModel` (an `image-models` catalog id, `gpt_image_2` by default). | One image at that model: 4 credits with the default | With `imageUrl` or `generatePortrait` the answer is `202` and `imageStatus` is `PROCESSING`. Poll [Get Character](/api-reference/character/details) until it is `COMPLETED` (`imageUrl` is set) or `FAILED`. A failed portrait gives its credits back. A portrait is charged like the dashboard's **Generate** button: a BYOK team needs its OpenRouter key (otherwise `402 missing_credentials`, nothing saved), and a managed team needs a plan and the credits for one image (otherwise `402`, nothing saved). ```bash cURL theme={null} 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 }' ``` ```javascript JavaScript theme={null} 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); ``` ```python Python theme={null} 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"]) ``` ```json 202 theme={null} { "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 } } ``` ```json 400 theme={null} { "success": false, "message": "description: Required to generate a portrait" } ``` ## Errors | Status | Message | Cause | | - | - | - | | 400 | `Invalid JSON body` | The body is not JSON. | | 400 | `name: Required` | No `name`, or an empty one. Longer than 60 characters is refused too. | | 400 | `presetId: Invalid preset "…"` | Not a `visual-styles` id, or another team's custom style. | | 400 | `mediaId: Pass only one of mediaId, imageUrl or generatePortrait` | More than one photo source. | | 400 | `mediaId: Image "…" not found in your library` | Not an image of your library (another team's, a video, a missing or malformed id). | | 400 | `mediaId: Media "…" is not ready (status PROCESSING)` | The image is still being imported or uploaded. | | 400 | `imageUrl: Must be a public https URL` | Not a URL, not `https`, or a local or private address. | | 400 | `description: Required to generate a portrait` | `generatePortrait` without a `description`. | | 400 | `imageModel: Invalid image model "…"` | Not an `image-models` id. `imageModel` without `generatePortrait` is refused too. | | 401 | `code: "not_authenticated"` | Missing or invalid `x-api-key`. | | 402 | `missing_credentials`, `subscription_required` or `INSUFFICIENT_CREDITS` | Only with `generatePortrait`: no OpenRouter key (BYOK), no plan, or not enough credits for the portrait. Nothing was saved. | | 403 | `code: "entitlement_required"` | Your team does not have the Hooked app product. | A URL that cannot be downloaded, a file that is not an image or a portrait the model refuses do not answer an error here: `imageStatus` becomes `FAILED`. Set another photo with [Update Character](/api-reference/character/update). ## OpenAPI ````yaml POST /v1/character/create openapi: 3.0.0 info: title: Hooked API version: 1.0.0 description: AI Video Generation API servers: - url: https://api.hooked.so security: - ApiKeyAuth: [] tags: - name: Videos description: Create projects, follow them and render videos - name: Account Analysis description: Analyze TikTok and YouTube accounts - name: Channels description: Connected social accounts you publish to - name: Publish description: Schedule videos to your connected accounts - name: Images description: 'Image editing: background removal and expansion' - name: Media description: 'Your media library: list, import from a URL, upload a file' - name: Avatars description: Your team's own avatars (Actors) and their Hook + Demo reactions paths: /v1/character/create: post: tags: [] summary: Create Character description: >- Saves a Cinematic character, like Studio → Characters: a name, a visual description, a voice description, a style and at most one photo source (`mediaId`, `imageUrl` or `generatePortrait`). Answers 201 with the character, or 202 when its photo is still being imported or generated: poll Get Character until `imageStatus` is `COMPLETED` or `FAILED`. operationId: createCharacter parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: type: object required: - name properties: name: type: string maxLength: 60 description: How the story calls the character (and its `@mention`). description: type: string maxLength: 2000 description: >- What the character looks like. Required with `generatePortrait`. voiceProfile: type: string maxLength: 500 description: How the character sounds, in words. presetId: type: string description: >- Visual style of a generated portrait: a `visual-styles` catalog id or your `custom-`. Default `cinematic`. mediaId: type: string description: >- An image of your media library (from List Media or an import), `COMPLETED`. Free. imageUrl: type: string format: uri description: >- A public https JPEG, PNG, WEBP or GIF. It is imported into your library after the response (free, counted against your storage); `imageStatus` is `PROCESSING` until then. generatePortrait: type: boolean description: >- `true` generates a portrait from `description` in the character's style, after the response. Charged one image at `imageModel` (4 credits with the default); given back if it fails. imageModel: type: string description: >- Image model for `generatePortrait` (an `image-models` catalog id). Default `gpt_image_2`. example: name: Mia description: Late 20s, red curly hair, denim jacket voiceProfile: Warm, slightly husky, speaks fast generatePortrait: true responses: '201': description: Character created, with its photo (or none) content: application/json: schema: type: object required: - success - data properties: success: type: boolean message: type: string data: $ref: '#/components/schemas/CharacterWritten' example: success: true message: Character created data: id: cm4xa1b2c0001cd34ef56gh78 name: Mia description: Late 20s, red curly hair, denim jacket voiceProfile: Warm, slightly husky, speaks fast presetId: cinematic imageUrl: https://files.hooked.so/team/public/mia--fid--1a2b.png imageStatus: COMPLETED createdAt: '2026-09-30T18:00:00.000Z' creditsCharged: 0 '202': description: >- Character created; its photo is being imported or generated (`imageStatus: PROCESSING`) content: application/json: schema: type: object required: - success - data properties: success: type: boolean message: type: string data: $ref: '#/components/schemas/CharacterWritten' example: 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 '400': description: Invalid body, photo or style; nothing was saved or charged content: application/json: schema: $ref: '#/components/schemas/ValidationError400' example: success: false message: 'description: Required to generate a portrait' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/EntitlementRequired' '409': $ref: '#/components/responses/IdempotencyInProgress' '422': $ref: '#/components/responses/IdempotencyMismatch' '429': $ref: '#/components/responses/RateLimited429' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error500' example: success: false message: Failed to create the character security: - ApiKeyAuth: [] components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false description: >- 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](/guides/idempotency). schema: type: string minLength: 1 maxLength: 255 pattern: ^[\x20-\x7E]+$ example: order-1042-video schemas: CharacterWritten: description: The character as saved, and what it cost. allOf: - $ref: '#/components/schemas/Character' - type: object required: - creditsCharged properties: creditsCharged: type: number description: >- Credits taken for a generated portrait (0 for anything else, and on BYOK). Given back if the portrait fails. ValidationError400: type: object description: >- The request is invalid. `message` is `: ` when a field is to blame. properties: success: type: boolean enum: - false message: type: string required: - success - message example: success: false message: 'webhook: Must be a valid HTTPS URL' Error500: type: object properties: success: type: boolean enum: - false message: type: string error: type: string description: Present on some endpoints example: success: false message: Internal server error Character: type: object description: >- A Cinematic character of your team (Studio → Characters in the dashboard). Pass its `id` in `characterIds` of Create Cinematic Video. required: - id - name - description - voiceProfile - presetId - imageUrl - imageStatus - createdAt properties: id: type: string description: Pass it in `characterIds`. name: type: string description: The character's name, as the story calls it. description: type: string nullable: true description: The visual description you gave it. voiceProfile: type: string nullable: true description: How the character sounds, in words. It drives the AI-imagined voice. presetId: type: string nullable: true description: >- The visual style its portrait is generated in (a `visual-styles` catalog id or your `custom-`). imageUrl: type: string nullable: true description: >- Its reference photo, as a signed URL that expires. `null` until `imageStatus` is `COMPLETED`. imageStatus: type: string enum: - NONE - PROCESSING - COMPLETED - FAILED description: >- `NONE`: no photo. `PROCESSING`: a photo imported from `imageUrl` or a generated portrait is on its way. `COMPLETED`: `imageUrl` is set. `FAILED`: the import or the portrait failed (a portrait's credits are given back); set another photo with Update Character. createdAt: type: string format: date-time Error401: type: object description: Missing or invalid `x-api-key`. properties: code: type: string enum: - not_authenticated message: type: string example: Not authenticated errorCode: type: string enum: - NOT_AUTHENTICATED details: type: object additionalProperties: type: string example: code: not_authenticated message: Not authenticated errorCode: NOT_AUTHENTICATED details: x-api-key: Header not provided or API Key invalid MissingCredentials402: type: object description: >- BYOK team without the provider keys this request uses. Nothing was created or charged. Add the keys in Settings → AI keys. properties: success: type: boolean enum: - false description: Present when raised by the spend check code: type: string enum: - missing_credentials errorCode: type: string enum: - MISSING_CREDENTIALS missingProviders: type: array items: type: string enum: - openrouter - elevenlabs - gemini - bria - firecrawl message: type: string details: type: object required: - code - errorCode - missingProviders - message example: code: missing_credentials message: >- Your team uses its own provider keys (BYOK) and these are missing or invalid: OpenRouter, ElevenLabs. Add them in Settings → AI keys. errorCode: MISSING_CREDENTIALS missingProviders: - openrouter - elevenlabs details: {} SubscriptionRequired402: type: object description: Managed team (generates with Hooked's keys) without a live subscription. properties: success: type: boolean enum: - false code: type: string enum: - subscription_required errorCode: type: string enum: - SUBSCRIPTION_REQUIRED message: type: string required: - success - code - errorCode - message example: 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. InsufficientCredits402: type: object description: >- Not enough credits for this request. `creditsNeeded` / `creditsAvailable` are included when the estimate is known. properties: success: type: boolean enum: - false errorCode: type: string enum: - INSUFFICIENT_CREDITS message: type: string creditsNeeded: type: number creditsAvailable: type: number required: - success - errorCode - message example: success: false errorCode: INSUFFICIENT_CREDITS message: Not enough credits to perform this action creditsNeeded: 40 creditsAvailable: 12 EntitlementRequired403: type: object description: >- Valid key, but the team does not have the product this endpoint belongs to. properties: code: type: string enum: - entitlement_required error: type: string enum: - entitlement_required message: type: string product: type: string example: app required: - code - error - message - product example: code: entitlement_required error: entitlement_required message: This endpoint requires the "app" product. product: app responses: Unauthorized: description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/Error401' PaymentRequired: description: >- Payment required: a BYOK team is missing provider keys (nothing was created or charged), a managed team has no live subscription, or there are not enough credits. content: application/json: schema: oneOf: - $ref: '#/components/schemas/MissingCredentials402' - $ref: '#/components/schemas/SubscriptionRequired402' - $ref: '#/components/schemas/InsufficientCredits402' examples: missingCredentials: value: code: missing_credentials message: >- Your team uses its own provider keys (BYOK) and these are missing or invalid: OpenRouter, ElevenLabs. Add them in Settings → AI keys. errorCode: MISSING_CREDENTIALS missingProviders: - openrouter - elevenlabs details: {} subscriptionRequired: value: 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. insufficientCredits: value: success: false errorCode: INSUFFICIENT_CREDITS message: Not enough credits to perform this action creditsNeeded: 40 creditsAvailable: 12 EntitlementRequired: description: The team does not have the product this endpoint needs content: application/json: schema: $ref: '#/components/schemas/EntitlementRequired403' IdempotencyInProgress: description: >- A request with the same `Idempotency-Key` is still running. Retry in a few seconds. content: application/json: schema: type: object properties: success: type: boolean enum: - false code: type: string message: type: string details: type: object additionalProperties: true required: - success - code - message example: success: false code: idempotency_conflict message: A request with this Idempotency-Key is still in progress details: {} IdempotencyMismatch: description: >- The `Idempotency-Key` was already used with a different body. Use a new key for a new request. content: application/json: schema: type: object properties: success: type: boolean enum: - false code: type: string message: type: string details: type: object additionalProperties: true required: - success - code - message example: success: false code: idempotency_mismatch message: Idempotency-Key was used with a different request details: {} RateLimited429: description: >- Your team is over a rate limit: 30 POST requests per minute, 120 other requests per minute, or 3 downloads of your URLs running at once. Nothing ran and nothing was charged: wait `Retry-After` seconds and send the request again. See [Rate limits](/guides/error-handling#rate-limits-429). headers: Retry-After: description: Seconds to wait before sending again. schema: type: integer X-RateLimit-Limit: description: The limit of the bucket you hit (not sent for the download cap). schema: type: integer X-RateLimit-Remaining: description: 'Requests left in this window: 0 (not sent for the download cap).' schema: type: integer X-RateLimit-Reset: description: >- When the window ends, in Unix seconds (not sent for the download cap). schema: type: integer content: application/json: schema: type: object properties: success: type: boolean enum: - false errorCode: type: string enum: - RATE_LIMITED message: type: string retryAfterSeconds: type: integer required: - success - errorCode - message - retryAfterSeconds example: success: false errorCode: RATE_LIMITED message: >- Rate limit exceeded: 30 POST requests per minute per team. Retry after 12 s. retryAfterSeconds: 12 securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.