> ## 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.
# Quick Start: Character 3D
> Extract a downloadable 3D Gaussian splat from a character image.
Create a Character with `type=vsplat` to extract a 3D Gaussian splat (`.vsplat`) instead of the render-ready 2D Character. When it's ready, fetch its signed download URL from [Export 3D Character](/v1/api-reference/characters/export). Pass `type=all` instead of `vsplat` if you also want the 2D render kept on the same Character — see the [Character Quickstart](/v1/guides/quickstart-character) for that path alone.
Set `VIGGLE_API_KEY` and run the example below as-is — it uses a Viggle-hosted sample image, so you don't need to prepare your own character image first.
## What you need
* An API key from the [Viggle Dashboard](https://portal.viggle.ai/keys), exported as `VIGGLE_API_KEY`
The examples below reference a placeholder sample asset URL (`https://assets.viggle.ai/samples/character.png`). Swap in your own `image`/`image_url`, or Viggle's published sample asset once available.
## Create, poll, and export the Character
```bash cURL theme={null}
#!/usr/bin/env bash
set -euo pipefail
response=$(curl -s -X POST "https://apis.viggle.ai/v1/characters" \
-H "Authorization: Bearer $VIGGLE_API_KEY" \
-F "image_url=https://assets.viggle.ai/samples/character.png" \
-F "type=vsplat")
character_id=$(echo "$response" | jq -r '.id')
for _ in $(seq 1 60); do
character=$(curl -s "https://apis.viggle.ai/v1/characters/$character_id" \
-H "Authorization: Bearer $VIGGLE_API_KEY")
status=$(echo "$character" | jq -r '.status')
case "$status" in
ready)
exported=$(curl -s "https://apis.viggle.ai/v1/characters/$character_id/export?download_type=vsplat" \
-H "Authorization: Bearer $VIGGLE_API_KEY")
echo "$exported" | jq -r '.vsplat_url'
exit 0
;;
failed)
echo "Character failed: $(echo "$character" | jq -c '.error')" >&2
exit 1
;;
esac
sleep 3
done
echo "Timed out waiting for character $character_id" >&2
exit 1
```
```javascript Node theme={null}
const baseUrl = "https://apis.viggle.ai/v1";
const headers = { Authorization: `Bearer ${process.env.VIGGLE_API_KEY}` };
async function createCharacter() {
const form = new FormData();
form.append("image_url", "https://assets.viggle.ai/samples/character.png");
form.append("type", "vsplat");
const response = await fetch(`${baseUrl}/characters`, {
method: "POST",
headers,
body: form,
});
if (!response.ok) {
const body = await response.json().catch(() => ({}));
throw new Error(`HTTP ${response.status}: ${JSON.stringify(body.error ?? body)}`);
}
return response.json();
}
async function waitForCharacter(id) {
for (let attempt = 0; attempt < 60; attempt++) {
const response = await fetch(`${baseUrl}/characters/${id}`, { headers });
if (!response.ok) {
const body = await response.json().catch(() => ({}));
throw new Error(`HTTP ${response.status}: ${JSON.stringify(body.error ?? body)}`);
}
const character = await response.json();
if (["ready", "failed"].includes(character.status)) return character;
await new Promise((resolve) => setTimeout(resolve, 3000));
}
throw new Error(`Timed out waiting for character ${id}`);
}
const created = await createCharacter();
const character = await waitForCharacter(created.id);
if (character.status !== "ready") {
throw new Error(`Character failed: ${JSON.stringify(character.error)}`);
}
const exportResponse = await fetch(
`${baseUrl}/characters/${character.id}/export?download_type=vsplat`,
{ headers },
);
if (!exportResponse.ok) {
const body = await exportResponse.json().catch(() => ({}));
throw new Error(`HTTP ${exportResponse.status}: ${JSON.stringify(body.error ?? body)}`);
}
const exported = await exportResponse.json();
console.log(exported.vsplat_url);
```
```python Python theme={null}
import os
import time
import requests
base_url = "https://apis.viggle.ai/v1"
headers = {"Authorization": f"Bearer {os.environ['VIGGLE_API_KEY']}"}
response = requests.post(
f"{base_url}/characters",
headers=headers,
files={"image_url": (None, "https://assets.viggle.ai/samples/character.png")},
data={"type": "vsplat"},
)
response.raise_for_status()
character = response.json()
for _ in range(60):
if character["status"] in {"ready", "failed"}:
break
time.sleep(3)
response = requests.get(f"{base_url}/characters/{character['id']}", headers=headers)
response.raise_for_status()
character = response.json()
else:
raise TimeoutError(f"Timed out waiting for character {character['id']}")
if character["status"] != "ready":
error = character.get("error") or {}
raise RuntimeError(f"failed: {error.get('code')} {error.get('message')}")
exported = requests.get(
f"{base_url}/characters/{character['id']}/export",
params={"download_type": "vsplat"},
headers=headers,
)
exported.raise_for_status()
print(exported.json()["vsplat_url"])
```
## Response
```json theme={null}
{
"id": "char_550e8400-e29b-41d4-a716-446655440000",
"status": "ready",
"download_type": "vsplat",
"vsplat_url": "https://assets.viggle.ai/results/character.vsplat",
"thumbnail_url": null,
"created_at": "2026-07-31T09:15:22+00:00",
"updated_at": "2026-07-31T09:16:40+00:00",
"error": null
}
```
Poll `GET /v1/characters/{character_id}` every 3 seconds until `status` is `ready` or `failed`. Once ready, request `GET /v1/characters/{character_id}/export?download_type=vsplat` for the signed `vsplat_url` — it's valid for 1 hour and re-signed on every call, so re-request it rather than caching it. Add `enhance=true` to the create request for the higher-quality extraction pass (a different price — see below), or `render_thumbnail=true` to also get a `thumbnail_url` back from the same export call.
See [Pricing and retention](/v1/pricing#character-3d) for `vsplat`/`enhance`/`all` pricing.
See every request field, including `model_precision`, `filter_low_quality`, and `joint_set`.