Quick Start: Character 3D

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. Pass type=all instead of vsplat if you also want the 2D render kept on the same Character — see the Character Quickstart 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, 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

#!/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

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);

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

{
  "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 for vsplat/enhance/all pricing.

Create Character (from Image)

See every request field, including model_precision, filter_low_quality, and joint_set.

Get Started

Guides

Production

Quick Start: Character 3D

What you need

Create, poll, and export the Character

Response

Create Character (from Image)

​What you need

​Create, poll, and export the Character

​Response

Create Character (from Image)

What you need

Create, poll, and export the Character

Response