Riggle VRM API — reference
One REST API takes a 3D character, rigged or not, or a picture of one, and gives back a VRM 1.0 that talks and blinks. This page is the whole reference: authentication, prices, every endpoint, the conversion object and the errors.
The Riggle VRM API converts a .glb or .vrm (rigged or unrigged, up to 100 MB) or a .png/.jpg of one character into a VRM 1.0 with humanoid bones, five visemes (aa, ih, ee, oh, ou), blink, blinkLeft, blinkRight, happy, angry, surprised, and lookAt when the rig has eye bones. It is three calls: POST /conversions, poll GET /conversions/{id} every 3-5 seconds, then GET /conversions/{id}/vrm. A model costs 10 API tokens ($1.00 to $1.50), a picture 25, and a failed conversion returns its tokens automatically.
Quick start
Make a key at app.riggle3d.com/developers. A key works once a pack of API tokens is bought; there are no free tokens. Then:
export RIGGLE_API_KEY=rgl_...
API=https://app.riggle3d.com/api/v1
# 1. start a conversion (10 API tokens)
id=$(curl -s -X POST $API/conversions \
-H "Authorization: Bearer $RIGGLE_API_KEY" \
-F file=@character.glb | jq -r .id)
# 2. poll until it is no longer processing
until [ "$(curl -s $API/conversions/$id \
-H "Authorization: Bearer $RIGGLE_API_KEY" | jq -r .status)" != processing ]
do sleep 4; done
# 3. download the VRM
curl -s -o character.vrm $API/conversions/$id/vrm \
-H "Authorization: Bearer $RIGGLE_API_KEY"A rigged model takes 1-3 minutes, a picture 3-6. The same flow as a zero-dependency Python and Node client, plus more curl examples, is in github.com/riggle3d/glb-to-vrm.
Basics and authentication
- Base URL:
https://app.riggle3d.com/api/v1 - Auth:
Authorization: Bearer rgl_…on every request. Keys are made and revoked on the developers page; the secret is shown once, so store it when you create it. - Requests are
multipart/form-data(the uploads) or have no body. Responses are JSON, except the file downloads. - Everything is asynchronous. Create a conversion, poll it every 3-5 seconds until
statusissucceededorfailed, then download. - Automatic. No step needs a person. Rigged models, unrigged models and pictures all go through the same three calls.
- OpenAPI: the 3.1 spec is at riggle3d.com/openapi.json, for code generators and API tools.
API tokens and prices
The API is paid in API tokens, a balance of its own. They are bought on the developers page and do not expire. They are not the Studio tokens of the web app: neither kind pays for the other's actions, and they cannot be exchanged.
| Action | API tokens |
|---|---|
Model (.glb / .vrm, rigged or not) → VRM | 10 |
Picture (.png / .jpg) → 3D model → VRM | 25 |
…with the picture redrawn first (fix=true, only when it needed it) | +2 |
Picture redrawn on its own (POST /pictures/fix) | 2 |
| Status, list, downloads, previews, delete | 0 |
| Pack | API tokens | Price | Per VRM from a model | Per VRM from a picture |
|---|---|---|---|---|
| Starter | 100 | $15 | $1.50 | $3.75 |
| Builder | 500 | $60 | $1.20 | $3.00 |
| Scale | 2,500 | $250 | $1.00 | $2.50 |
Tokens are taken when the conversion is created and returned automatically if it fails.
Endpoints
| Method and path | What it does |
|---|---|
POST /conversions | Start a conversion from a model or a picture |
GET /conversions/{id} | Poll one conversion |
GET /conversions?limit=20 | The latest conversions, newest first (max 100) |
GET /conversions/{id}/vrm | The VRM file |
GET /conversions/{id}/preview.mp4 | A video of every expression played back |
GET /conversions/{id}/preview/{name}.png | One still |
DELETE /conversions/{id} | Delete a conversion and its files |
POST /pictures/fix | Start a redraw of a picture on its own |
GET /pictures/fix/{id} | Poll one redraw |
GET /pictures/fix/{id}/image | The redrawn PNG |
GET /account | Token balance, prices and the concurrency limit |
POST /conversions
Multipart fields:
| Field | |
|---|---|
file | A .glb or .vrm, up to 100 MB. A rigged humanoid, or an unrigged one. |
image | Instead of file: a .png or .jpg up to 20 MB, showing one whole character, standing, facing the camera. |
name | Optional. What to call the conversion; defaults to the file's name. |
fix | Optional, pictures only. true: if the picture check finds a problem, the picture is redrawn as one full-body front view before the model is made. +2 API tokens, charged only when it is redrawn. |
force | Optional, pictures only. true: skip the picture check and use the picture as it is. Wins over fix: with both, nothing is checked or redrawn. |
The picture check. Before anything is charged, a picture is checked for being one whole humanoid character, head to feet, facing the camera. One that is not is refused with 422 picture_rejected and a problems list (not_humanoid, multi_view, not_full_body, not_front, each with a message). Send another picture, or the same one with fix=true or force=true. The check is advice: it can be wrong about a usable picture, which is what force is for, and when it cannot be run the picture goes through.
The optional header Idempotency-Key: <any string up to 64 chars> makes a retry safe: a second request with the same key returns the first conversion instead of making, and charging for, another one.
curl -s -X POST https://app.riggle3d.com/api/v1/conversions \
-H "Authorization: Bearer $RIGGLE_API_KEY" \
-H "Idempotency-Key: order-1042" \
-F file=@character.glb \
-F name=robotReturns 201 with the conversion object. Errors: 400 invalid_request, 400 unsupported_file, 401 unauthorized, 402 insufficient_tokens, 413 file_too_large, 422 picture_rejected, 429 too_many_active (3 conversions in flight per account) and 503 unavailable (pictures are switched off).
GET /conversions/{id}
Returns the conversion object. Call it every 3-5 seconds until status leaves processing.
GET /conversions?limit=20
The latest conversions, newest first. limit goes up to 100. The response is {"object": "list", "data": [conversion, …]}.
GET /conversions/{id}/vrm
The VRM file. Answers 409 not_ready until status is succeeded.
GET /conversions/{id}/preview.mp4
A video in which every expression is played back. Use it to check a result without opening a VRM viewer.
GET /conversions/{id}/preview/{name}.png
One still. name is one of the keys of preview_images on the conversion object.
DELETE /conversions/{id}
Returns 204. The files are erased for good within a week. Deleting a conversion that is still running does not return its tokens.
POST /pictures/fix
The redraw on its own. Multipart field image (a .png or .jpg up to 20 MB), an optional name, and an optional Idempotency-Key header. It always redraws the picture as one full-body, front-facing view of the character on a plain background; there is no check first. It costs 2 API tokens, taken when the fix is made and returned if no picture comes back.
It is a job like a conversion: the answer is 201 with the picture-fix object, then you poll.
{"id": "5f0c…", "object": "picture_fix", "status": "processing",
"name": "hero.png", "cost": 2, "refunded": false,
"created_at": "2026-11-17T10:02:11Z", "finished_at": null,
"error": null, "image_url": null}status goes from processing to succeeded or failed. A fix is usually done in under a minute; poll every 3-5 seconds. On failure error is {"code": "fix_failed", "message": "…"} and refunded is true. image_url is set on success.
Errors: 400 invalid_request, 400 unsupported_file, 402 insufficient_tokens, 413 file_too_large, 429 too_many_active (3 fixes in flight per account, counted apart from conversions) and 503 unavailable.
GET /pictures/fix/{id}
Returns the picture-fix object. Call it every 3-5 seconds until status leaves processing.
GET /pictures/fix/{id}/image
The redrawn PNG. Answers 409 not_ready until status is succeeded. The picture is kept for 7 days, and it can be sent straight to POST /conversions as image.
The example runs a fix from start to finish and then converts the result.
# 1. start the redraw (2 API tokens)
fix=$(curl -s -X POST $API/pictures/fix \
-H "Authorization: Bearer $RIGGLE_API_KEY" \
-F image=@character.png | jq -r .id)
# 2. poll until it is no longer processing
until [ "$(curl -s $API/pictures/fix/$fix \
-H "Authorization: Bearer $RIGGLE_API_KEY" | jq -r .status)" != processing ]
do sleep 4; done
# 3. download the redrawn PNG and look at it
curl -s -o fixed.png $API/pictures/fix/$fix/image \
-H "Authorization: Bearer $RIGGLE_API_KEY"
# 4. send it like any other picture (25 API tokens)
curl -s -X POST $API/conversions \
-H "Authorization: Bearer $RIGGLE_API_KEY" \
-F image=@fixed.pngGET /account
{"object": "account", "api_tokens": 90,
"prices": {"model_to_vrm": 10, "image_to_vrm": 25, "fix_picture": 2},
"max_active_conversions": 3}The conversion object
{
"id": "0b8f6c0e-3f0e-4d8e-9a57-0c9a2f6f1c11",
"object": "conversion",
"status": "processing",
"stage": "building_vrm",
"name": "robot",
"input": "model",
"cost": 10,
"refunded": false,
"created_at": "2026-11-17T10:02:11Z",
"finished_at": null,
"error": null,
"warnings": [],
"vrm_url": null,
"preview_video_url": null,
"preview_images": {}
}status:processing, thensucceededorfailed.stagewhile processing:generating_model(pictures only),rigging(unrigged models only),marking_face,building_vrm. It isnullonce the conversion has finished.input:modelorimage.cost: the API tokens taken for it.refundedistruewhen they have been returned.error:null, or{"code": "conversion_failed", "message": "…"}when the conversion failed.refundedis thentrue.warnings: a list of strings. The avatar was built, but look at the preview: for example the face marking was low-confidence, or a viseme barely moves.vrm_url,preview_video_urlandpreview_images({name: url}) are set on success. They are absolute API URLs and need the sameAuthorizationheader, so they cannot be handed to a browser as they are.
Errors
Every error has the same shape, with a matching HTTP status:
{"error": {"code": "not_ready", "message": "…"}}| Code | HTTP | When |
|---|---|---|
invalid_request | 400 | The request is not one of the forms described here |
unsupported_file | 400 | The upload is not a file type the endpoint takes |
unauthorized | 401 | No valid key in the Authorization header |
insufficient_tokens | 402 | Not enough API tokens. required and available sit beside code inside error |
not_found | 404 | No such conversion on this account |
not_ready | 409 | The VRM, or a redrawn picture, was asked for before status was succeeded |
file_too_large | 413 | Over 100 MB for a model, or 20 MB for a picture |
picture_rejected | 422 | A picture did not pass the picture check. Comes with a problems list; nothing is charged |
too_many_active | 429 | 3 conversions are already in flight on the account, or 3 picture fixes; the two are counted apart |
unavailable | 503 | Pictures are switched off |
A 402 looks like this:
{"error": {"code": "insufficient_tokens", "message": "…",
"required": 25, "available": 10}}And a 422:
{"error": {"code": "picture_rejected", "message": "…",
"problems": [{"code": "not_full_body", "message": "…"}]}}A conversion that was accepted and then could not be finished is not an HTTP error: it is a conversion whose status is failed, with error.code set to conversion_failed and its tokens returned.
Python example
The three calls with requests:
import os, time, requests
API = "https://app.riggle3d.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['RIGGLE_API_KEY']}"}
with open("character.glb", "rb") as f:
r = requests.post(f"{API}/conversions", headers=HEADERS, files={"file": f})
if not r.ok:
raise SystemExit(r.json()["error"]["message"])
conv = r.json()
while conv["status"] == "processing":
time.sleep(4)
conv = requests.get(f"{API}/conversions/{conv['id']}", headers=HEADERS).json()
if conv["status"] == "failed":
raise SystemExit(conv["error"]["message"]) # the tokens are already back
for w in conv["warnings"]:
print("warning:", w) # built, but look at the preview
vrm = requests.get(conv["vrm_url"], headers=HEADERS) # an absolute URL
with open("character.vrm", "wb") as out:
out.write(vrm.content)For a client with no dependencies at all, copy the one in the examples repository.
Node example
Node 18 or later, using the built-in fetch, FormData and Blob. Save it as an .mjs file:
import { readFile, writeFile } from "node:fs/promises";
const API = "https://app.riggle3d.com/api/v1";
const headers = { Authorization: `Bearer ${process.env.RIGGLE_API_KEY}` };
const form = new FormData();
form.append("file", new Blob([await readFile("character.glb")]), "character.glb");
const res = await fetch(`${API}/conversions`, { method: "POST", headers, body: form });
if (!res.ok) throw new Error((await res.json()).error.message);
let conv = await res.json();
while (conv.status === "processing") {
await new Promise((r) => setTimeout(r, 4000));
conv = await (await fetch(`${API}/conversions/${conv.id}`, { headers })).json();
}
if (conv.status === "failed") throw new Error(conv.error.message); // tokens are already back
for (const w of conv.warnings) console.warn("warning:", w); // built, but look at the preview
const vrm = await fetch(conv.vrm_url, { headers }); // an absolute URL
await writeFile("character.vrm", Buffer.from(await vrm.arrayBuffer()));To start from a picture instead, send the field image in place of file; everything after that is the same. See the image to VRM API page.
What comes out
A VRM 1.0 file with:
- the humanoid bones mapped;
- the five visemes:
aa,ih,ee,oh,ou; blink,blinkLeftandblinkRight;happy,angryandsurprised;- lookAt, when the rig has eye bones.
How good the face looks depends on the model: a character modelled with its mouth open gives the most natural mouth shapes, while a closed mouth gives softer movement. When a result deserves a look, warnings says so; play preview.mp4 before you ship the file to a user.
The output is VRM 1.0 only. The 52 ARKit blendshapes are not part of it.
Limits
- Input:
.glbor.vrmup to 100 MB;.pngor.jpgup to 20 MB. A file is uploaded in the request; there is no other way to pass one. - Concurrency: 3 conversions in flight per account. A fourth gets
429 too_many_active; wait for one to finish. Picture fixes have their own limit of 3, counted apart from conversions. - Time: 1-3 minutes for a rigged model, 3-6 for a picture. Poll every 3-5 seconds.
- Characters: humanoids. One whole, standing, front-facing character for a picture.
- Deleted conversions: files are erased for good within a week.
Task pages: GLB to VRM API, image to VRM API and adding visemes and blinks to a VRM via the API. To convert one model by hand in the browser instead, use the GLB to VRM converter.
Get an API key
Make a key, buy a pack, and send your first model. Packs start at $15 for 100 tokens, and a failed conversion returns its tokens.
Get an API keyFAQ
Is there a free tier?
No. There are no free API tokens: a key works once a pack is bought. Packs are 100 tokens for $15, 500 for $60 or 2,500 for $250, and a failed conversion returns its tokens automatically.
What happens to my tokens when a conversion fails?
They are returned automatically. The conversion's status becomes failed, error.code is conversion_failed and refunded is true. The one exception is a conversion you delete while it is still running: that does not return its tokens.
Are API tokens the same as the tokens in the Riggle web app?
No. API tokens are a separate balance, bought on the developers page. The web app's Studio tokens do not pay for API calls, API tokens do not pay for downloads in the web app, and the two cannot be exchanged.
Do API tokens expire?
No.
Are there webhooks?
No. The API is polled: ask for GET /conversions/{id} every 3-5 seconds until status is succeeded or failed.
Is there an SDK?
There is no package to install. The examples repository at github.com/riggle3d/glb-to-vrm has a zero-dependency Python client, a zero-dependency Node client and curl examples that you can copy into your project.
Can I pass a URL instead of uploading the file?
No. The model or the picture is uploaded in the POST /conversions request as multipart/form-data.
Can I send an FBX?
No. The API takes .glb and .vrm for models, and .png and .jpg for pictures. Export the FBX to a binary glTF (.glb) first, for example from Blender.
What happens if my picture is not usable?
A picture is checked before anything is charged. If it is not one whole humanoid character, head to feet, facing the camera, the request gets 422 picture_rejected with a list of problems. Send another picture, add fix=true to have it redrawn as a full-body front view first (2 more API tokens, only when it is redrawn), or add force=true to skip the check.
How many conversions can run at once?
Three per account. A fourth POST /conversions gets 429 too_many_active until one of them finishes.
How do I know whether the result is good?
Read warnings on the conversion object and play preview.mp4. A warning means the avatar was built but something deserves a look, for example the face was found with low confidence or a viseme barely moves.
Does the model have to be rigged?
No. An unrigged humanoid .glb works too; Riggle adds the skeleton, and while it does, stage reads rigging. It costs the same 10 API tokens and comes out the same VRM 1.0.