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

> Turn a photo into one of your team's own avatars

## Overview

Makes one of your team's own avatars (an Actor under **My Actors** in the dashboard) from a photo, the same way **Upload a photo** does. Send the photo as a public `https` URL (`imageUrl`) or as an image of your [media library](/api-reference/media/list) (`mediaId`). The photo is copied, tagged (age group, skin tone, setting, expression, and gender unless you set it), and the avatar is ready at once: the answer is `201` with `status: "COMPLETED"`. Use its `id` as `avatarId` in the create endpoints.

<Info>
  JPEG, PNG or WEBP, up to **20 MB**. The type is read from the file itself. Managed teams pay **200 credits**, the dashboard's custom actor price. BYOK teams pay no credits; the tagging runs on the team's own OpenRouter key.
</Info>

The avatar keeps its own copy of the photo, so deleting the avatar never touches your library image, and deleting the library image never breaks the avatar.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.hooked.so/v1/avatar/create/from-photo" \
    -H "x-api-key: your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{ "name": "Maya", "imageUrl": "https://cdn.example.com/team/maya.jpg", "gender": "Female" }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.hooked.so/v1/avatar/create/from-photo", {
    method: "POST",
    headers: { "x-api-key": process.env.HOOKED_API_KEY, "Content-Type": "application/json" },
    body: JSON.stringify({ name: "Maya", imageUrl: "https://cdn.example.com/team/maya.jpg", gender: "Female" }),
  });
  const { data } = await response.json();
  console.log(data.id, data.status); // use data.id as avatarId
  ```

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

  response = requests.post(
      "https://api.hooked.so/v1/avatar/create/from-photo",
      headers={"x-api-key": os.environ["HOOKED_API_KEY"]},
      json={"name": "Maya", "imageUrl": "https://cdn.example.com/team/maya.jpg", "gender": "Female"},
  )
  data = response.json()["data"]
  print(data["id"], data["status"])
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "success": true,
    "message": "Avatar created",
    "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",
      "usedCredits": 200
    }
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "message": "imageUrl: Must be a JPEG, PNG or WEBP image"
  }
  ```
</ResponseExample>

## Errors

| Status | Message | Cause |
| - | - | - |
| 400 | `Invalid JSON body` | The body is not JSON. |
| 400 | `name: Required` | No `name` (1-60 characters). |
| 400 | `imageUrl or mediaId is required` / `Send imageUrl or mediaId, not both` | Send exactly one photo. |
| 400 | `imageUrl: Must be a public https URL` | Not `https`, or a local or private address. |
| 400 | `imageUrl: Could not download the image (HTTP …)` | The URL did not answer the file. |
| 400 | `…: Must be a JPEG, PNG or WEBP image` / `…: The image is over 20 MB` | The file itself. |
| 400 | `mediaId: Image "…" not found in your library` | Not an image of your team's library. |
| 400 | `mediaId: Media "…" is not ready (status PROCESSING)` | An import or upload still running. |
| 400 | `gender: Must be Female or Male` | Leave it out to read it from the photo. |
| 401 | `code: "not_authenticated"` | Missing or invalid `x-api-key`. |
| 402 | `missing_credentials` / `subscription_required` / `INSUFFICIENT_CREDITS` | Nothing was downloaded or charged. |
| 403 | `code: "entitlement_required"` | Your team does not have the Hooked app product. |

<Tip>
  No photo? [Generate Avatar](/api-reference/avatar/generate) makes one from a description.
</Tip>


## OpenAPI

````yaml POST /v1/avatar/create/from-photo
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/create/from-photo:
    post:
      tags:
        - Avatars
      summary: Create Avatar from Photo
      description: >-
        Makes one of your team's own avatars from a photo, as **Upload a photo**
        does in the dashboard: a public `https` URL or an image of your media
        library. The photo is copied, tagged (age, skin tone, setting,
        expression; gender too unless you set it) and the avatar is ready at
        once (`201`, `status: COMPLETED`). Managed teams: 200 credits (the
        dashboard's custom actor price). BYOK teams: no credits; the tagging
        runs on the team's own OpenRouter key.
      operationId: createAvatarFromPhoto
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  maxLength: 60
                  description: The avatar's name (1-60 characters).
                imageUrl:
                  type: string
                  format: uri
                  description: >-
                    Public `https` URL of a JPEG, PNG or WEBP photo, up to 20
                    MB. Required unless `mediaId` is given; send one of the two.
                mediaId:
                  type: string
                  description: >-
                    Id of a `COMPLETED` image of your media library. Required
                    unless `imageUrl` is given.
                gender:
                  type: string
                  enum:
                    - Female
                    - Male
                  description: Leave it out to read it from the photo.
            example:
              name: Maya
              imageUrl: https://cdn.example.com/team/maya.jpg
              gender: Female
      responses:
        '201':
          description: Avatar created and ready
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - data
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  data:
                    allOf:
                      - $ref: '#/components/schemas/CustomAvatar'
                      - type: object
                        required:
                          - usedCredits
                        properties:
                          usedCredits:
                            type: number
                            description: Credits charged (200 on managed teams; 0 on BYOK).
              example:
                success: true
                message: Avatar created
                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'
                  usedCredits: 200
        '400':
          description: >-
            Invalid JSON, a missing or invalid field (`name: Required`,
            `imageUrl or mediaId is required`, `gender: ...`), a URL that is not
            public `https` or cannot be downloaded, a file that is not a JPEG,
            PNG or WEBP image or is over 20 MB, or a `mediaId` that is not a
            ready image of your library
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError400'
              example:
                success: false
                message: 'imageUrl: Must be a JPEG, PNG or WEBP image'
        '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':
          $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:
    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.
    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'
    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
    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.