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

> One of your team's own avatars, with its Hook + Demo reactions

## Overview

Returns one of your team's own avatars: its status, image and tags, and its Hook + Demo `reactions`. Poll it after [Generate Avatar](/api-reference/avatar/generate) until `status` is `COMPLETED` or `FAILED`, and after [Create Reaction](/api-reference/avatar/create-reaction) until the reaction is.

Library avatars are not served here; [List Avatars](/api-reference/avatar/list) has them. Another team's avatar, a deleted one or an id that is not one answers `404 Avatar not found`.

| `status` | Meaning |
| - | - |
| `PROCESSING` | A generation is running. `image` is `null`. |
| `COMPLETED` | Ready: use the `id` as `avatarId`. |
| `FAILED` | The generation failed and its credits were given back. A generation still running after 15 minutes reads `FAILED` too. |

Each reaction is `PROCESSING`, `COMPLETED` (with `videoUrl` and `thumbnailUrl`) or `FAILED`. The image and video URLs are signed and expire; read them again rather than storing them.

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

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.hooked.so/v1/avatar/cm7a1v9t20003ab12cd34ef56", {
    headers: { "x-api-key": process.env.HOOKED_API_KEY },
  });
  const { data } = await response.json();
  console.log(data.status, data.reactions.map((reaction) => [reaction.id, reaction.status]));
  ```

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

  response = requests.get(
      "https://api.hooked.so/v1/avatar/cm7a1v9t20003ab12cd34ef56",
      headers={"x-api-key": os.environ["HOOKED_API_KEY"]},
  )
  data = response.json()["data"]
  print(data["status"], [(r["id"], r["status"]) for r in data["reactions"]])
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "message": "Avatar fetched successfully",
    "data": {
      "id": "cm7a1v9t20003ab12cd34ef56",
      "name": "Maya",
      "type": "Realistic",
      "gender": "Female",
      "age": "Young Adult",
      "image": "https://cdn.hooked.so/team/public/image/cm7a1v9t2/maya.png?X-Amz-Signature=...",
      "status": "COMPLETED",
      "situation": ["Kitchen"],
      "emotions": ["Happy"],
      "skinTone": "medium",
      "isCustom": true,
      "source": "custom",
      "createdAt": "2026-10-05T09:12:44.000Z",
      "reactions": [
        {
          "id": "cm7a2r4k80011ab12gh78ij90",
          "reaction": "surprise",
          "status": "COMPLETED",
          "videoUrl": "https://cdn.hooked.so/team/public/avatar-reactions/cm7a2r4k8.mp4?X-Amz-Signature=...",
          "thumbnailUrl": "https://cdn.hooked.so/team/public/avatar-reactions/cm7a2r4k8.jpg?X-Amz-Signature=...",
          "createdAt": "2026-10-05T09:20:03.000Z"
        }
      ]
    }
  }
  ```

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


## OpenAPI

````yaml GET /v1/avatar/{avatarId}
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/avatar/{avatarId}:
    get:
      tags:
        - Avatars
      summary: Get Avatar
      description: >-
        One of your team's own avatars, with its Hook + Demo reactions. Poll it
        after Generate Avatar until `status` is `COMPLETED` or `FAILED`, and
        after Create Reaction until the reaction is. Library avatars are not
        served here (see List Avatars).
      operationId: getAvatar
      parameters:
        - name: avatarId
          in: path
          required: true
          schema:
            type: string
          description: >-
            The id of one of your team's own avatars (from List Avatars with
            `type=custom`, or a create call). Library avatars are not accepted
            here.
      responses:
        '200':
          description: The avatar
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - data
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/CustomAvatar'
              example:
                success: true
                message: Avatar fetched successfully
                data:
                  id: cm7a1v9t20003ab12cd34ef56
                  name: Maya
                  type: Realistic
                  gender: Female
                  age: Young Adult
                  image: >-
                    https://cdn.hooked.so/team/public/image/cm7a1v9t2/maya.png?X-Amz-Signature=...
                  status: COMPLETED
                  situation:
                    - Kitchen
                  emotions:
                    - Happy
                  skinTone: medium
                  isCustom: true
                  source: custom
                  createdAt: '2026-10-05T09:12:44.000Z'
                  reactions:
                    - id: cm7a2r4k80011ab12gh78ij90
                      reaction: surprise
                      status: COMPLETED
                      videoUrl: >-
                        https://cdn.hooked.so/team/public/avatar-reactions/cm7a2r4k8.mp4?X-Amz-Signature=...
                      thumbnailUrl: >-
                        https://cdn.hooked.so/team/public/avatar-reactions/cm7a2r4k8.jpg?X-Amz-Signature=...
                      createdAt: '2026-10-05T09:20:03.000Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/EntitlementRequired'
        '404':
          description: >-
            No such avatar of your team (a library avatar, another team's, a
            deleted or a malformed id answer the same)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound404'
              example:
                success: false
                message: Avatar not found
        '429':
          $ref: '#/components/responses/RateLimited429'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    CustomAvatar:
      type: object
      description: >-
        One of your team's own avatars (an Actor under My Actors in the
        dashboard).
      required:
        - id
        - name
        - status
        - isCustom
        - source
      properties:
        id:
          type: string
          description: >-
            Pass it as `avatarId` in the create endpoints once `status` is
            `COMPLETED`.
        name:
          type: string
        type:
          type: string
          description: '`Realistic` (made from a photo) or `AI` (generated).'
        gender:
          type: string
          description: >-
            `Female` or `Male`. Read from the photo unless you set it; a
            generation shows `Female` until it is `COMPLETED`.
        age:
          type: string
          description: Age group read from the photo, for example `Young Adult` or `Adult`.
        image:
          type: string
          nullable: true
          description: The avatar image (signed, expiring). `null` until `COMPLETED`.
        status:
          type: string
          enum:
            - PROCESSING
            - COMPLETED
            - FAILED
          description: >-
            `PROCESSING` while a generation runs, `COMPLETED` when the avatar
            can be used, `FAILED` when the generation failed (its credits are
            given back). A generation still `PROCESSING` after 15 minutes reads
            `FAILED`.
        situation:
          type: array
          items:
            type: string
          description: Setting tags read from the photo.
        emotions:
          type: array
          items:
            type: string
          description: Expression tags read from the photo.
        skinTone:
          type: string
          description: '`light`, `medium-light`, `medium` or `dark`.'
        isCustom:
          type: boolean
          enum:
            - true
        source:
          type: string
          enum:
            - custom
        createdAt:
          type: string
          format: date-time
        reactions:
          type: array
          items:
            $ref: '#/components/schemas/AvatarReaction'
          description: >-
            Only in Get Avatar: the avatar's Hook + Demo reactions, newest
            first.
    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
    AvatarReaction:
      type: object
      description: >-
        A Hook + Demo reaction of one of your avatars: a short clip of the
        avatar making a face, used as `avatarId` in Create Hook Demo once
        `COMPLETED`.
      required:
        - id
        - reaction
        - status
      properties:
        id:
          type: string
          description: >-
            The reaction id. Once `COMPLETED`, pass it as `avatarId` to Create
            Hook Demo; it is also listed in GET /v1/catalog/reactions.
        reaction:
          type: string
          enum:
            - surprise
            - shock
            - excitement
            - smirk
            - confusion
            - disgust
            - happy
            - laughing
            - whispers
            - nervous
            - frustrated
            - crying
            - turn_reveal
            - side_look
            - double_take
            - lean_in
            - custom
          description: The reaction asked for.
        status:
          type: string
          enum:
            - PROCESSING
            - COMPLETED
            - FAILED
          description: >-
            `PROCESSING` while the still and the clip are made (about 1-3
            minutes), then `COMPLETED` or `FAILED` (a failed reaction gives its
            credits back).
        videoUrl:
          type: string
          nullable: true
          description: The clip (signed, expiring). `null` until `COMPLETED`.
        thumbnailUrl:
          type: string
          nullable: true
          description: A still of the clip (signed, expiring). `null` until `COMPLETED`.
        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
    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
    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
  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
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error500'
  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.