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

# Create Avatar

> Create an asynchronous image-to-3D conversion.

`POST /v1/avatars` starts a 3D Avatar conversion. This is a conversion operation, not a reusable Character asset.

## Request parameters

Send `multipart/form-data`.

| Parameter | Type | Required | Default | Description                           |
| --------- | ---- | :------: | ------- | ------------------------------------- |
| `image`   | file |    Yes   | —       | Image used to generate the 3D Avatar. |

## Response parameters

Returns `200 OK` with a conversion object.

| Field        | Type           | Always present | Description                                           |
| ------------ | -------------- | :------------: | ----------------------------------------------------- |
| `id`         | string         |       Yes      | Public Avatar ID beginning with `avatar_`.            |
| `status`     | string         |       Yes      | `queued`, `processing`, `ready`, or `failed`.         |
| `model_url`  | string or null |       Yes      | Downloadable 3D result when ready.                    |
| `created_at` | string or null |       Yes      | ISO 8601 creation timestamp when available.           |
| `updated_at` | string or null |       Yes      | ISO 8601 most-recent update timestamp when available. |
| `error`      | object or null |       Yes      | Structured failure details when status is `failed`.   |

```json theme={null}
{"id":"avatar_123abc","status":"queued","model_url":null,"created_at":null,"updated_at":null,"error":null}
```

## Examples

<CodeGroup>
  ```go Go theme={null}
  file, err := os.Open("character.png")
  if err != nil { panic(err) }
  defer file.Close()

  body := &bytes.Buffer{}
  writer := multipart.NewWriter(body)
  part, _ := writer.CreateFormFile("image", "character.png")
  io.Copy(part, file)
  writer.Close()

  req, _ := http.NewRequest("POST", "https://apis.viggle.ai/v1/avatars", body)
  req.Header.Set("Authorization", "Bearer "+os.Getenv("VIGGLE_API_KEY"))
  req.Header.Set("Content-Type", writer.FormDataContentType())

  resp, err := http.DefaultClient.Do(req)
  if err != nil { panic(err) }
  defer resp.Body.Close()
  ```

  ```javascript JavaScript theme={null}
  const form = new FormData();
  form.append("image", imageFile);

  const response = await fetch("https://apis.viggle.ai/v1/avatars", {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.VIGGLE_API_KEY}` },
    body: form,
  });
  const avatar = await response.json();
  ```

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

  with open("character.png", "rb") as image:
      response = requests.post(
          "https://apis.viggle.ai/v1/avatars",
          headers={"Authorization": f"Bearer {os.environ['VIGGLE_API_KEY']}"},
          files={"image": image},
      )
  response.raise_for_status()
  avatar = response.json()
  ```

  ```bash cURL theme={null}
  curl -X POST "https://apis.viggle.ai/v1/avatars" \
    -H "Authorization: Bearer $VIGGLE_API_KEY" \
    -F "image=@character.png"
  ```
</CodeGroup>


## OpenAPI

````yaml POST /v1/avatars
openapi: 3.0.3
info:
  title: Viggle API
  description: Generate AI-powered character animation videos
  version: 2.0.0
  contact:
    name: Viggle Support
    url: https://viggle.ai
servers:
  - url: https://apis.viggle.ai
    description: Production server
security: []
paths:
  /v1/avatars:
    post:
      summary: Create Avatar
      operationId: v1CreateAvatar
      responses:
        '200':
          description: Avatar

````