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

> Create an asynchronous character-animation video render.

`POST /v1/renders` combines one Character source and one Motion source. Send `multipart/form-data`.

## Request parameters

| Parameter          | Type   |       Required       | Default    | Description                                               |
| ------------------ | ------ | :------------------: | ---------- | --------------------------------------------------------- |
| `character_id`     | string | One character source | —          | Ready `char_` ID to reuse a Character.                    |
| `image`            | file   | One character source | —          | Character image uploaded directly.                        |
| `image_url`        | string | One character source | —          | Public URL for a character image.                         |
| `motion_id`        | string |   One motion source  | —          | Ready `mot_` ID to reuse a Motion.                        |
| `motion_video`     | file   |   One motion source  | —          | Driving video uploaded directly.                          |
| `motion_video_url` | string |   One motion source  | —          | Public URL for a driving video.                           |
| `background_mode`  | string |          No          | `original` | Output background: `original`, `solid`, or `transparent`. |
| `bg_color`         | string |     With `solid`     | —          | RGB value as `R,G,B`, such as `0,255,0`.                  |

For each source family, provide one source. `bg_color` is only valid with `background_mode=solid`.

## Response parameters

Returns `200 OK` with a Render object.

| Field          | Type            | Always present | Description                                                |
| -------------- | --------------- | :------------: | ---------------------------------------------------------- |
| `id`           | string          |       Yes      | Public Render ID beginning with `render_`.                 |
| `status`       | string          |       Yes      | `queued`, `processing`, `ready`, `failed`, or `cancelled`. |
| `progress`     | integer or null |       Yes      | Progress from 0 to 100 when available.                     |
| `stage`        | string or null  |       Yes      | Current processing stage when available.                   |
| `video_url`    | string or null  |       Yes      | Finished video URL when ready.                             |
| `alpha_url`    | string or null  |       Yes      | Alpha video URL for transparent output, when available.    |
| `created_at`   | string or null  |       Yes      | ISO 8601 creation timestamp.                               |
| `completed_at` | string or null  |       Yes      | ISO 8601 completion timestamp.                             |
| `error`        | object or null  |       Yes      | Failure details when the Render fails.                     |

```json theme={null}
{"id":"render_789ghi","status":"queued","progress":0,"stage":null,"video_url":null,"alpha_url":null,"created_at":"2026-07-21T10:00:00Z","completed_at":null,"error":null}
```

## Examples

<CodeGroup>
  ```go Go theme={null}
  body:=&bytes.Buffer{}; w:=multipart.NewWriter(body); image,_:=os.Open("character.png"); defer image.Close(); video,_:=os.Open("dance.mp4"); defer video.Close(); p,_:=w.CreateFormFile("image","character.png"); io.Copy(p,image); p,_=w.CreateFormFile("motion_video","dance.mp4"); io.Copy(p,video); w.WriteField("background_mode","original"); w.Close(); req,_:=http.NewRequest("POST","https://apis.viggle.ai/v1/renders",body); req.Header.Set("Authorization","Bearer "+os.Getenv("VIGGLE_API_KEY")); req.Header.Set("Content-Type",w.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("motion_video",videoFile); form.append("background_mode","original"); const response=await fetch("https://apis.viggle.ai/v1/renders",{method:"POST",headers:{Authorization:`Bearer ${process.env.VIGGLE_API_KEY}`},body:form}); const render=await response.json();
  ```

  ```python Python theme={null}
  import os, requests
  with open("character.png","rb") as image, open("dance.mp4","rb") as video: response=requests.post("https://apis.viggle.ai/v1/renders",headers={"Authorization":f"Bearer {os.environ['VIGGLE_API_KEY']}"},files={"image":image,"motion_video":video},data={"background_mode":"original"})
  response.raise_for_status(); render=response.json()
  ```

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


## OpenAPI

````yaml POST /v1/renders
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/renders:
    post:
      summary: Create Render
      operationId: v1CreateRender
      responses:
        '200':
          description: Render

````