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

> Make a Hook + Demo reaction clip of one of your avatars

## Overview

Makes a reaction of one of your team's own avatars, the same way **Studio → Actors → Reactions** does in the dashboard: a still of the avatar making the face, animated into a short silent clip (5-6 seconds). The call answers `202` at once; the reaction takes about 1-3 minutes. Follow it in [Get Avatar](/api-reference/avatar/details) under `reactions`.

Once the reaction is `COMPLETED`, its `id` is an `avatarId` for [Create Hook Demo](/api-reference/video/hook-demo), and it is listed in [`GET /v1/catalog/reactions`](/api-reference/catalog/get) next to the library reactions. A reaction that is not finished is refused by Hook Demo with `400`.

<Info>
  Managed teams pay the still plus the clip at the models picked, the same price the dashboard quotes: **52 credits** with the defaults (GPT Image 2 + Grok Imagine). It is charged now and refunded if the reaction fails. BYOK teams pay no credits; the team's own OpenRouter key is used.
</Info>

| Field | Values |
| - | - |
| `reaction` | `surprise`, `shock`, `excitement`, `smirk`, `confusion`, `disgust`, `happy`, `laughing`, `whispers`, `nervous`, `frustrated`, `crying`, `turn_reveal`, `side_look`, `double_take`, `lean_in`, or `custom` with your own `customPrompt` |
| `model` | Image model for the still: an `id` of [`GET /v1/catalog/image-models`](/api-reference/catalog/get). Default `gpt_image_2` |
| `videoModel` | `grok_imagine_video` (default, cheapest), `seedance_2_0_fast`, `seedance_2_0_mini`, `seedance_2_0`, `kling_3_0`, `wan_2_7_i2v` |

The avatar must be `COMPLETED`. Library avatars already have their reactions in the catalog; this endpoint is for your own avatars.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.hooked.so/v1/avatar/cm7a1v9t20003ab12cd34ef56/reaction" \
    -H "x-api-key: your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{ "reaction": "surprise" }'
  ```

  ```javascript JavaScript theme={null}
  const avatarId = "cm7a1v9t20003ab12cd34ef56";
  const response = await fetch(`https://api.hooked.so/v1/avatar/${avatarId}/reaction`, {
    method: "POST",
    headers: { "x-api-key": process.env.HOOKED_API_KEY, "Content-Type": "application/json" },
    body: JSON.stringify({ reaction: "surprise" }),
  });
  const { data } = await response.json();
  // Poll GET /v1/avatar/{avatarId} until this reaction is COMPLETED, then use data.id as hook-demo avatarId
  console.log(data.id, data.status);
  ```

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

  avatar_id = "cm7a1v9t20003ab12cd34ef56"
  response = requests.post(
      f"https://api.hooked.so/v1/avatar/{avatar_id}/reaction",
      headers={"x-api-key": os.environ["HOOKED_API_KEY"]},
      json={"reaction": "surprise"},
  )
  data = response.json()["data"]
  print(data["id"], data["status"])
  ```
</RequestExample>

<ResponseExample>
  ```json 202 theme={null}
  {
    "success": true,
    "message": "Reaction generation started",
    "data": {
      "id": "cm7a2r4k80011ab12gh78ij90",
      "reaction": "surprise",
      "status": "PROCESSING",
      "videoUrl": null,
      "thumbnailUrl": null,
      "createdAt": "2026-10-05T09:20:03.000Z",
      "avatarId": "cm7a1v9t20003ab12cd34ef56",
      "usedCredits": 52
    }
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "message": "customPrompt: Required for the custom reaction"
  }
  ```
</ResponseExample>

## Errors

| Status | When |
| - | - |
| 400 | Invalid JSON, `reaction: Required`, an unknown `reaction`, `custom` without `customPrompt` (up to 1,000 characters), an invalid `model` or `videoModel`, or `Avatar is not ready (status …)` |
| 401 | Missing or invalid API key |
| 402 | BYOK without its keys, no live plan, or not enough credits. Nothing was created or charged |
| 403 | The team does not have the Hooked app product |
| 404 | `Avatar not found`: not one of your team's own avatars |


## OpenAPI

````yaml POST /v1/avatar/{avatarId}/reaction
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}/reaction:
    post:
      tags:
        - Avatars
      summary: Create Reaction
      description: >-
        Makes a Hook + Demo reaction of one of your team's own avatars, as
        **Studio → Actors → Reactions** does in the dashboard: a still of the
        avatar making the face, animated into a short silent clip (5-6 s).
        Answers `202` at once; it takes about 1-3 minutes. Follow it in Get
        Avatar (`reactions`). Once `COMPLETED`, its `id` is an `avatarId` for
        Create Hook Demo and it is listed in GET /v1/catalog/reactions. Managed
        teams pay the still plus the clip at the models picked (the price the
        dashboard quotes: 52 credits with the defaults, GPT Image 2 + Grok
        Imagine), charged now and refunded if it fails. BYOK teams: no credits;
        the team's own OpenRouter key is used.
      operationId: createAvatarReaction
      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.
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - reaction
              properties:
                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 face to make. `custom` takes your own `customPrompt`.
                customPrompt:
                  type: string
                  maxLength: 1000
                  description: >-
                    What the avatar does, for `reaction: custom` (required
                    then). Ignored for the other reactions.
                model:
                  type: string
                  default: gpt_image_2
                  description: >-
                    Image model for the still: an `id` of GET
                    /v1/catalog/image-models.
                videoModel:
                  type: string
                  enum:
                    - grok_imagine_video
                    - seedance_2_0_fast
                    - seedance_2_0_mini
                    - seedance_2_0
                    - kling_3_0
                    - wan_2_7_i2v
                  default: grok_imagine_video
                  description: Video model for the clip, cheapest first.
            example:
              reaction: surprise
      responses:
        '202':
          description: Reaction started
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - data
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    allOf:
                      - $ref: '#/components/schemas/AvatarReaction'
                      - type: object
                        required:
                          - usedCredits
                        properties:
                          usedCredits:
                            type: number
                            description: >-
                              Credits charged for the still and the clip (0 on
                              BYOK). Refunded if the reaction fails.
              example:
                success: true
                message: Reaction generation started
                data:
                  id: cm7a2r4k80011ab12gh78ij90
                  reaction: surprise
                  status: PROCESSING
                  videoUrl: null
                  thumbnailUrl: null
                  createdAt: '2026-10-05T09:20:03.000Z'
                  avatarId: cm7a1v9t20003ab12cd34ef56
                  usedCredits: 52
        '400':
          description: >-
            Invalid JSON, a missing or invalid field (`reaction: Required`,
            `customPrompt: Required for the custom reaction`, `model: ...`,
            `videoModel: ...`), or an avatar that is not ready (`Avatar is not
            ready (status PROCESSING)`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError400'
              example:
                success: false
                message: 'reaction: Required'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '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
        '409':
          $ref: '#/components/responses/IdempotencyInProgress'
        '422':
          $ref: '#/components/responses/IdempotencyMismatch'
        '429':
          $ref: '#/components/responses/RateLimited429'
        '500':
          $ref: '#/components/responses/InternalError'
      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:
    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
    ValidationError400:
      type: object
      description: >-
        The request is invalid. `message` is `<field>: <reason>` 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'
    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
    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
    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'
    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
    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.