> ## 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.

# Get Character

> One Cinematic character of your team

## Overview

Returns one of your team's Cinematic characters. Use it to check an id before passing it in `characterIds` of [Create Cinematic Video](/api-reference/video/cinematic). `imageUrl` is a signed URL that expires, or `null` when the character has no photo yet. After [Create Character](/api-reference/character/create) or [Update Character](/api-reference/character/update) with `imageUrl` or `generatePortrait`, poll this endpoint until `imageStatus` is `COMPLETED` (or `FAILED`). Free and safe to retry.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.hooked.so/v1/character/cm4xa1b2c0001cd34ef56gh78" \
    -H "x-api-key: your_api_key_here"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.hooked.so/v1/character/cm4xa1b2c0001cd34ef56gh78", {
    headers: { "x-api-key": process.env.HOOKED_API_KEY },
  });
  const { data: character } = await response.json();
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.get(
      "https://api.hooked.so/v1/character/cm4xa1b2c0001cd34ef56gh78",
      headers={"x-api-key": os.environ["HOOKED_API_KEY"]},
  )
  character = response.json()["data"]
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "message": "Character fetched successfully",
    "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"
    }
  }
  ```

  ```json 404 theme={null}
  {
    "success": false,
    "message": "Character not found"
  }
  ```
</ResponseExample>

## Errors

| Status | When |
| - | - |
| 401 | Missing or invalid API key (`code: "not_authenticated"`) |
| 403 | The team does not have the Hooked app product (`code: "entitlement_required"`) |
| 404 | No such character in your team. Another team's character, or an id that is not one, answers the same `Character not found` |


## OpenAPI

````yaml GET /v1/character/{characterId}
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/{characterId}:
    get:
      tags: []
      summary: Get Character
      description: One Cinematic character of your team.
      operationId: getCharacter
      parameters:
        - name: characterId
          in: path
          required: true
          schema:
            type: string
          description: The character id, from List Characters.
      responses:
        '200':
          description: Character found
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - data
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/Character'
                  message:
                    type: string
              example:
                success: true
                message: Character fetched successfully
                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'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/EntitlementRequired'
        '404':
          description: >-
            No such character in your team (another team's or a malformed id
            answers the same)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
              example:
                success: false
                message: Character not found
        '429':
          $ref: '#/components/responses/RateLimited429'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    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-<id>`).
        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
    NotFound404:
      type: object
      description: >-
        Not found. Another team's resource answers the same way as a missing
        one.
      properties:
        success:
          type: boolean
          enum:
            - false
        message:
          type: string
      required:
        - success
        - message
      example:
        success: false
        message: Project not found
    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
    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'
    EntitlementRequired:
      description: The team does not have the product this endpoint needs
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EntitlementRequired403'
    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.