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

> Create a reusable Character from an image.

Creates a reusable Character asset. The request is asynchronous; poll the Character until `status` is `ready` before using its ID in a Render.

## Request parameters

Send `multipart/form-data`.

| Parameter   | Type   | Required | Default | Description                                                                 |
| ----------- | ------ | :------: | ------- | --------------------------------------------------------------------------- |
| `image`     | file   |  One of  | —       | Character image uploaded from the client. PNG, JPEG, and WebP are accepted. |
| `image_url` | string |  One of  | —       | Publicly reachable URL for the character image.                             |
| `name`      | string |    No    | `""`    | Optional label displayed when listing the Character.                        |

Provide exactly one of `image` or `image_url`.

## Response parameters

Returns `200 OK` with a Character object.

| Field          | Type            | Always present | Description                                                                                                 |
| -------------- | --------------- | :------------: | ----------------------------------------------------------------------------------------------------------- |
| `id`           | string          |       Yes      | Public Character ID, for example `char_550e8400-e29b-41d4-a716-446655440000`. Store it exactly as returned. |
| `status`       | string          |       Yes      | Initial status is normally `queued`. Terminal values are `ready` and `failed`.                              |
| `name`         | string          |       Yes      | The supplied label, or an empty string.                                                                     |
| `progress`     | integer or null |       Yes      | Progress from 0 to 100 when available.                                                                      |
| `capabilities` | string\[]       |       Yes      | Empty until ready; ready Characters currently include `video_render`.                                       |
| `created_at`   | string or null  |       Yes      | ISO 8601 creation timestamp when available.                                                                 |
| `completed_at` | string or null  |       Yes      | ISO 8601 completion timestamp; `null` before completion.                                                    |
| `error`        | object or null  |       Yes      | Structured error when `status` is `failed`; otherwise `null`.                                               |

```json theme={null}
{
  "id": "char_550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "name": "Presenter",
  "progress": 0,
  "capabilities": [],
  "created_at": "2026-07-21T10:00:00Z",
  "completed_at": null,
  "error": null
}
```

## Examples

<CodeGroup>
  ```go Go theme={null}
  body := &bytes.Buffer{}
  writer := multipart.NewWriter(body)
  part, _ := writer.CreateFormFile("image", "character.png")
  file, _ := os.Open("character.png")
  defer file.Close()
  io.Copy(part, file)
  writer.WriteField("name", "Presenter")
  writer.Close()

  req, _ := http.NewRequest("POST", "https://apis.viggle.ai/v1/characters", 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);
  form.append("name", "Presenter");

  const response = await fetch("https://apis.viggle.ai/v1/characters", {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.VIGGLE_API_KEY}` },
    body: form,
  });
  const character = 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/characters",
          headers={"Authorization": f"Bearer {os.environ['VIGGLE_API_KEY']}"},
          files={"image": image},
          data={"name": "Presenter"},
      )
  response.raise_for_status()
  character = response.json()
  ```

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

## Next step

Use [Get Character](/v1/api-reference/characters) to poll the returned ID until it is ready.


## OpenAPI

````yaml POST /v1/characters
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/characters:
    post:
      summary: Create Character
      operationId: v1CreateCharacter
      responses:
        '200':
          description: Character

````