Extract Character (static-bin)

curl --request POST \
  --url https://apis.viggle.ai/api/extract/static-bin \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form images='@example-file' \
  --form model=v4_gaussian \
  --form task_id=ext_a1b2c3d4e5f60718 \
  --form render_thumbnail=false \
  --form render_source=full \
  --form render_rest=false

import requests

url = "https://apis.viggle.ai/api/extract/static-bin"

files = { "images": ("example-file", open("example-file", "rb")) }
payload = {
    "model": "v4_gaussian",
    "task_id": "ext_a1b2c3d4e5f60718",
    "render_thumbnail": "false",
    "render_source": "full",
    "render_rest": "false"
}
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('images', '<string>');
form.append('model', 'v4_gaussian');
form.append('task_id', 'ext_a1b2c3d4e5f60718');
form.append('render_thumbnail', 'false');
form.append('render_source', 'full');
form.append('render_rest', 'false');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://apis.viggle.ai/api/extract/static-bin', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://apis.viggle.ai/api/extract/static-bin",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"images\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"model\"\r\n\r\nv4_gaussian\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"task_id\"\r\n\r\next_a1b2c3d4e5f60718\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"render_thumbnail\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"render_source\"\r\n\r\nfull\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"render_rest\"\r\n\r\nfalse\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://apis.viggle.ai/api/extract/static-bin"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"images\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"model\"\r\n\r\nv4_gaussian\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"task_id\"\r\n\r\next_a1b2c3d4e5f60718\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"render_thumbnail\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"render_source\"\r\n\r\nfull\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"render_rest\"\r\n\r\nfalse\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://apis.viggle.ai/api/extract/static-bin")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"images\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"model\"\r\n\r\nv4_gaussian\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"task_id\"\r\n\r\next_a1b2c3d4e5f60718\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"render_thumbnail\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"render_source\"\r\n\r\nfull\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"render_rest\"\r\n\r\nfalse\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://apis.viggle.ai/api/extract/static-bin")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"images\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"model\"\r\n\r\nv4_gaussian\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"task_id\"\r\n\r\next_a1b2c3d4e5f60718\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"render_thumbnail\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"render_source\"\r\n\r\nfull\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"render_rest\"\r\n\r\nfalse\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "task_id": "ext_a1b2c3d4e5f60718",
  "kind": "static_bin",
  "workflow_id": "uorc-extract-ext_a1b2c3d4e5f60718",
  "status": "queued"
}

{
  "detail": {
    "error_code": "CS-UORC01-002",
    "message": "Validation failed. Check that the image file is present and model is a valid value."
  }
}

{
  "detail": "Invalid or missing API key. Pass it as Authorization: Bearer sk-..."
}

{
  "detail": {
    "error_code": "CS-UORC01-008",
    "message": "Insufficient credits. Top up your balance to continue."
  }
}

{
  "detail": {
    "error_code": "CS-UORC01-015",
    "message": "A task with this id already exists. Use a new task_id."
  }
}

{
  "detail": {
    "error_code": "CS-UORC01-016",
    "message": "Extract service is temporarily unavailable. Retry in a few seconds."
  }
}

POST

api

extract

static-bin

Extract Character (static-bin)

curl --request POST \
  --url https://apis.viggle.ai/api/extract/static-bin \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form images='@example-file' \
  --form model=v4_gaussian \
  --form task_id=ext_a1b2c3d4e5f60718 \
  --form render_thumbnail=false \
  --form render_source=full \
  --form render_rest=false

import requests

url = "https://apis.viggle.ai/api/extract/static-bin"

files = { "images": ("example-file", open("example-file", "rb")) }
payload = {
    "model": "v4_gaussian",
    "task_id": "ext_a1b2c3d4e5f60718",
    "render_thumbnail": "false",
    "render_source": "full",
    "render_rest": "false"
}
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('images', '<string>');
form.append('model', 'v4_gaussian');
form.append('task_id', 'ext_a1b2c3d4e5f60718');
form.append('render_thumbnail', 'false');
form.append('render_source', 'full');
form.append('render_rest', 'false');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://apis.viggle.ai/api/extract/static-bin', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://apis.viggle.ai/api/extract/static-bin",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"images\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"model\"\r\n\r\nv4_gaussian\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"task_id\"\r\n\r\next_a1b2c3d4e5f60718\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"render_thumbnail\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"render_source\"\r\n\r\nfull\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"render_rest\"\r\n\r\nfalse\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://apis.viggle.ai/api/extract/static-bin"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"images\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"model\"\r\n\r\nv4_gaussian\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"task_id\"\r\n\r\next_a1b2c3d4e5f60718\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"render_thumbnail\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"render_source\"\r\n\r\nfull\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"render_rest\"\r\n\r\nfalse\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://apis.viggle.ai/api/extract/static-bin")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"images\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"model\"\r\n\r\nv4_gaussian\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"task_id\"\r\n\r\next_a1b2c3d4e5f60718\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"render_thumbnail\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"render_source\"\r\n\r\nfull\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"render_rest\"\r\n\r\nfalse\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://apis.viggle.ai/api/extract/static-bin")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"images\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"model\"\r\n\r\nv4_gaussian\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"task_id\"\r\n\r\next_a1b2c3d4e5f60718\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"render_thumbnail\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"render_source\"\r\n\r\nfull\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"render_rest\"\r\n\r\nfalse\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "task_id": "ext_a1b2c3d4e5f60718",
  "kind": "static_bin",
  "workflow_id": "uorc-extract-ext_a1b2c3d4e5f60718",
  "status": "queued"
}

{
  "detail": {
    "error_code": "CS-UORC01-002",
    "message": "Validation failed. Check that the image file is present and model is a valid value."
  }
}

{
  "detail": "Invalid or missing API key. Pass it as Authorization: Bearer sk-..."
}

{
  "detail": {
    "error_code": "CS-UORC01-008",
    "message": "Insufficient credits. Top up your balance to continue."
  }
}

{
  "detail": {
    "error_code": "CS-UORC01-015",
    "message": "A task with this id already exists. Use a new task_id."
  }
}

{
  "detail": {
    "error_code": "CS-UORC01-016",
    "message": "Extract service is temporarily unavailable. Retry in a few seconds."
  }
}

Upload a single image and get back a 3D character bin (character_stripped.bin). Send it as multipart/form-data, and if you like, we’ll render a default-view thumbnail too.

Asynchronous task. This endpoint returns a task_id immediately and does not block. Poll Get Extract Task until status is complete.State machine: queued → processing → complete | failed

Binary upload. Send the raw file directly as multipart/form-data — no URL or storage path is required.

Image formats: PNG, JPG/JPEG, and WebP are accepted. Images larger than 4K are automatically downscaled.

Parameters

Send as multipart/form-data.

Parameter	Type	Required	Default	Description
`images`	file	✅	—	Input image (PNG, JPG, WebP). Currently a single image. Images larger than 4K are downscaled.
`model`	string		`v4_gaussian`	Extraction model: `v4_gaussian` or `v4_mobile`.
`render_thumbnail`	boolean		`false`	Also render a default-view thumbnail.
`render_source`	string		`full`	Thumbnail render source: `pkl`, `full`, or `stripped`.
`render_rest`	boolean		`false`	Render the rest pose (skip skinning).
`task_id`	string		—	Optional client-supplied id for idempotent retries.

Pricing

Character extraction (one 3D character) costs 25 credits. Credits are reserved when the task is created, settled when the task completes successfully, and automatically refunded if the task fails. Insufficient balance returns 402 CS-UORC01-008.

Idempotent retries

The task_id form field is optional. Supplying your own task_id enables idempotent retries: re-creating with the same task_id returns 409 CS-UORC01-015. If omitted, the server generates one (format ext_ + 16 hex chars).

Response

{
  "task_id": "ext_a1b2c3d4e5f60718",
  "kind": "static_bin",
  "workflow_id": "uorc-extract-ext_a1b2c3d4e5f60718",
  "status": "queued"
}

workflow_id is an internal processing identifier — clients can ignore it and poll using task_id.

Error Handling

If the request fails, the response includes a structured error with an error_code:

{
  "detail": {
    "error_code": "CS-UORC01-015",
    "error": "task_conflict",
    "message": "A task with this id already exists."
  }
}

Common error codes for this endpoint:

Code	Cause	Fix
`CS-UORC01-006`	Missing API key	Add `Authorization: Bearer sk-...` header
`CS-UORC01-007`	Invalid or expired API key	Check your key is correct
`CS-UORC01-002`	Validation failed (empty file, invalid enum)	Check your form fields
`CS-UORC01-008`	Insufficient credits	Top up credits
`CS-UORC01-015`	`task_id` already in use	Use a new `task_id`
`CS-UORC01-016`	Extract service temporarily unavailable	Retry in a few seconds (HTTP 502)

See Error Codes for the full list. When contacting [email protected], include the error_code and your task_id.

Examples

import requests

url = "https://apis.viggle.ai/api/extract/static-bin"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

with open("character.png", "rb") as img:
    resp = requests.post(
        url,
        headers=headers,
        files={"images": ("character.png", img, "image/png")},
        data={"model": "v4_gaussian", "render_thumbnail": "true"},
    )

data = resp.json()
if "detail" in data:
    print(f"Error {data['detail']['error_code']}: {data['detail']['message']}")
else:
    print(f"Task created: {data['task_id']}")
    print(f"Poll: GET /api/extract/{data['task_id']}")

const form = new FormData();
form.append("images", await fetch("character.png").then(r => r.blob()), "character.png");
form.append("model", "v4_gaussian");
form.append("render_thumbnail", "true");

const resp = await fetch("https://apis.viggle.ai/api/extract/static-bin", {
  method: "POST",
  headers: { "Authorization": "Bearer YOUR_API_KEY" },
  body: form,
});

const data = await resp.json();
if (data.detail) {
  console.error(`Error ${data.detail.error_code}: ${data.detail.message}`);
} else {
  console.log(`Task created: ${data.task_id}`);
}

curl -s -X POST "https://apis.viggle.ai/api/extract/static-bin" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "model=v4_gaussian" \
  -F "render_thumbnail=true"

Next Steps

After creating the task, poll Get Extract Task every 5-10 seconds. When status is complete, read the signed download links from result (stripped_bin_url, and render_output_urls when render_thumbnail was set).

Authorizations

Authorization

string

header

required

API key passed as Bearer token

Body

multipart/form-data

images

file

required

Input image file (currently a single image). PNG, JPG, WebP, etc.

model

enum<string>

default:v4_gaussian

Extraction model.

Available options:

v4_gaussian,

v4_mobile

task_id

string

Optional client-supplied task id for idempotent retries. Reusing an existing id returns 409. If omitted, the server generates one (format ext_ + 16 hex chars).

Example:

"ext_a1b2c3d4e5f60718"

render_thumbnail

boolean

default:false

Whether to also render a default-view thumbnail.

render_source

enum<string>

default:full

Thumbnail render source.

Available options:

pkl,

full,

stripped

render_rest

boolean

default:false

Render rest pose (skip skinning).

Response

Extract task created

task_id

string

Task id. Use it to poll GET /api/extract/{task_id}.

Example:

"ext_a1b2c3d4e5f60718"

kind

enum<string>

Extract task kind.

Available options:

static_bin,

dynamic_fbx

Example:

"static_bin"

workflow_id

string

Internal processing identifier. Clients can ignore it — poll with task_id.

Example:

"uorc-extract-ext_a1b2c3d4e5f60718"

status

string

Example:

"queued"

Get Job Status Extract Motion (dynamic-fbx)

Characters

Scenes

Render

Extract

Credits

Extract Character (static-bin)

Parameters

Pricing

Idempotent retries

Response

Error Handling

Examples

Next Steps

Authorizations

Body

Response

​Parameters

​Pricing

​Idempotent retries

​Response

​Error Handling

​Examples

​Next Steps

Authorizations

Body

Response

Parameters

Pricing

Idempotent retries

Response

Error Handling

Examples

Next Steps