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

# Avatars

> Create, edit and track avatar generations with the Hoox API

## Avatar Workflow

Create avatars from a text prompt or from existing images, then generate additional looks by editing. You can receive webhooks on completion or poll a status endpoint.

<CardGroup cols={2}>
  <Card title="From Prompt" icon="sparkles">
    Create a brand new avatar using a text prompt and a visual style.
  </Card>

  <Card title="From Images" icon="images">
    Build an avatar instantly from your own reference images. No generation cost.
  </Card>

  <Card title="Edit Look" icon="wand-magic">
    Generate a new look from an existing one using a prompt and optional extra images.
  </Card>

  <Card title="Status & Webhooks" icon="bell">
    Track generation status via polling or receive webhooks on completion/failure.
  </Card>
</CardGroup>

## Endpoints

### Create from Prompt

POST `/api/public/v1/avatar/create`

Request body:

```json theme={null}
{
  "prompt": "Young entrepreneur in a modern office, confident smile",
  "style": "iphone",
  "format": "vertical",
  "name": "Alex",
  "place": "office",
  "resolution": "2K",
  "elementImages": [
    "https://your-domain.com/logo.png"
  ],
  "webhook_url": "https://your-domain.com/webhooks/avatar"
}
```

Response:

```json theme={null}
{
  "avatar_id": "avtr_abc",
  "look_id": "look_123"
}
```

<Info>
  Creation costs 2 credits for 2K resolution and 4 credits for 4K. Status starts as `pending` and becomes `ready` or `error`.
</Info>

### Create from Images

POST `/api/public/v1/avatar/create`

Request body:

```json theme={null}
{
  "imageUrls": [
    "https://your-domain.com/img1.jpg",
    "https://your-domain.com/img2.jpg"
  ],
  "name": "Jordan",
  "place": "studio",
  "webhook_url": "https://your-domain.com/webhooks/avatar"
}
```

Response:

```json theme={null}
{
  "avatar_id": "avtr_xyz",
  "look_id": "look_a"
}
```

<Info>
  No generation cost; looks are created instantly with status `ready`.
</Info>

### Edit an Avatar Look

POST `/api/public/v1/avatar/edit`

Request body:

```json theme={null}
{
  "avatar_id": "avtr_abc",
  "look_id": "look_123",
  "prompt": "Same person, podcast scene, warm cinematic lighting",
  "style": "podcast",
  "format": "vertical",
  "resolution": "2K",
  "images": [
    "https://your-domain.com/extra-reference.jpg"
  ],
  "webhook_url": "https://your-domain.com/webhooks/avatar"
}
```

Response:

```json theme={null}
{
  "avatar_id": "avtr_abc",
  "look_id": "look_edit_789"
}
```

<Info>
  Editing costs 2 credits for 2K resolution and 4 credits for 4K per new look. A new look is created in `pending` status and updated to `ready` or `error`.
</Info>

## Status & Webhooks

### Poll Generation Status

GET `/api/public/v1/avatar/status?avatar_id={avatarId}&look_id={lookId}`

Example response:

```json theme={null}
{
  "avatar_id": "avtr_abc",
  "look_id": "look_edit_789",
  "status": "completed",
  "result": {
    "thumbnail_url": "https://media.hoox.video/…/image.jpg"
  }
}
```

### Webhook Payloads

On success:

```json theme={null}
{
  "job_id": "look_edit_789",
  "status": "completed",
  "result": { "thumbnail_url": "https://media.hoox.video/.../image.jpg" }
}
```

On failure:

```json theme={null}
{
  "job_id": "look_edit_789",
  "status": "failed",
  "error": { "code": "GENERATION_FAILED", "message": "Edit failed" }
}
```

<Info>
  Provide a `webhook_url` in the request body to receive asynchronous updates. Otherwise, use the status endpoint to poll.
</Info>

## Next Steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/api-reference/avatar/list">
    Detailed endpoints for avatar creation and editing
  </Card>

  <Card title="Video Generation Overview" icon="film" href="/video-generation/overview">
    Generate videos using your avatars
  </Card>
</CardGroup>