> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hoox.video/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Avatar

> Create an avatar from a prompt or from image URLs. If a prompt is provided, it takes priority.

## Overview

This endpoint creates a new avatar with one or more looks. You can create an avatar in two ways:

1. **Prompt-based creation**: Provide a text prompt and style to generate an avatar using AI. The prompt takes priority if provided.
2. **Image-based creation**: Provide image URLs that will be used as-is for the avatar looks (not as reference images).

<Warning>
  When using images, they are used directly as the avatar looks, not as reference images for generation.
</Warning>

## Authentication

<Info>
  This endpoint requires API key authentication. Include your API key in the `Authorization` header.
</Info>

## Request Body

<ParamField body="prompt" type="string">
  Text prompt describing the avatar to generate. If provided, prompt-based generation takes priority over images.
</ParamField>

<ParamField body="style" type="string" default="iphone">
  Avatar style. Available options: `iphone`, `selfie`, `podcast`, `car`, `conference`. Optional, defaults to `iphone`.
</ParamField>

<ParamField body="format" type="string" default="vertical">
  Image format: `vertical` (9:16) or `horizontal` (16:9). Only used for prompt-based generation.
</ParamField>

<ParamField body="name" type="string">
  Custom name for the avatar.
</ParamField>

<ParamField body="place" type="string">
  Place or context for the avatar (e.g., "office", "studio").
</ParamField>

<ParamField body="images" type="array">
  Array of image URLs. These images are used as-is for the avatar looks (not as reference). Only used if no prompt is provided.
</ParamField>

<ParamField body="elementImages" type="array">
  Array of image URLs to use as reference elements during generation. These images guide the AI to incorporate specific visual elements (logos, products, objects) into the generated avatar. Only used with prompt-based generation.
</ParamField>

<ParamField body="resolution" type="string" default="2K">
  Output image resolution: `2K` or `4K`. Optional, defaults to `2K`. Note that `4K` generation costs more credits.
</ParamField>

<ParamField body="webhook_url" type="string">
  URL to receive webhook notifications when generation completes.
</ParamField>

## Response

<ResponseField name="avatar_id" type="string">
  Unique identifier for the created avatar.
</ResponseField>

<ResponseField name="look_id" type="string">
  Unique identifier for the first look of the avatar. For prompt-based generation, this look will be in "pending" status initially.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://app.hoox.video/api/public/v1/avatar/create" \
    -H "Authorization: Bearer your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "Professional portrait of a CTO, smiling, natural lighting",
      "style": "selfie",
      "format": "vertical",
      "name": "Alex",
      "place": "office",
      "resolution": "2K",
      "webhook_url": "https://example.com/webhooks/avatar"
    }'
  ```

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

  url = "https://app.hoox.video/api/public/v1/avatar/create"
  headers = {
      "Authorization": "Bearer your_api_key",
      "Content-Type": "application/json"
  }

  data = {
      "prompt": "Professional portrait of a CTO, smiling, natural lighting",
      "style": "selfie",
      "format": "vertical",
      "name": "Alex",
      "place": "office",
      "resolution": "2K",
      "webhook_url": "https://example.com/webhooks/avatar"
  }

  response = requests.post(url, headers=headers, json=data)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://app.hoox.video/api/public/v1/avatar/create', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your_api_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      prompt: "Professional portrait of a CTO, smiling, natural lighting",
      style: "selfie",
      format: "vertical",
      name: "Alex",
      place: "office",
      resolution: "2K",
      webhook_url: "https://example.com/webhooks/avatar"
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```bash With Element Images theme={null}
  curl -X POST "https://app.hoox.video/api/public/v1/avatar/create" \
    -H "Authorization: Bearer your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "Professional woman holding a product, office background",
      "style": "selfie",
      "format": "vertical",
      "elementImages": [
        "https://example.com/logo.png",
        "https://example.com/product.jpg"
      ],
      "resolution": "4K",
      "webhook_url": "https://example.com/webhooks/avatar"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "avatar_id": "avtr_123",
    "look_id": "look_abc"
  }
  ```

  ```json Error 400 - Validation Failed theme={null}
  {
    "error": "Validation failed",
    "details": [
      {
        "code": "INVALID_VALUE",
        "message": "prompt is required",
        "field": "prompt"
      }
    ]
  }
  ```

  ```json Error 402 - Insufficient Credits theme={null}
  {
    "error": "Insufficient credits",
    "required": 2,
    "available": 1
  }
  ```
</ResponseExample>

## Creation Methods

### 1. Prompt-based Creation

Provide a `prompt` (and optionally `style`, defaulting to "iphone"). The AI will generate the avatar image. The first look will start in "pending" status and become "ready" once generation completes.

**With Element Images**: You can also provide `elementImages` (or `elements`) to guide the AI generation with specific visual references. This is useful for incorporating logos, products, or specific objects into the generated avatar.

### 2. Image-based Creation

Provide an `images` array with image URLs. These images are used directly as the avatar looks (not as reference). The looks are immediately available with status "ready".

## Credit Costs

* **Prompt-based creation (2K)**: 2 credits
* **Prompt-based creation (4K)**: 4 credits
* **Image-based creation**: Free (no credits charged)

## Next Steps

1. **Check Status**: Use `/avatar/status` endpoint to monitor the generation progress
2. **Edit Avatar**: Use `/avatar/edit` endpoint to create new looks from existing ones

## Error Codes

* `INVALID_VALUE`: Invalid parameter value (webhook\_url, style, or images)
* `INSUFFICIENT_CREDITS`: Not enough credits to create the avatar
* `AVATAR_LIMIT_REACHED`: Maximum number of avatars reached for your plan
* `SPACE_NOT_FOUND`: Space doesn't exist
* `FAILED_TO_PERSIST`: Error saving avatar to database
* `GENERATION_FAILED`: Avatar generation failed (async error sent via webhook)