Image to VRM API — a picture in, a talking VRM 1.0 out
One request takes a PNG or JPG of a character and ends in a VRM 1.0 that talks and blinks. You do not chain a 3D generator, an auto-rigger and a converter yourself.
To turn an image into a VRM through an API, POST a .png or .jpg (up to 20 MB) as the field image to https://app.riggle3d.com/api/v1/conversions. You get back a VRM 1.0 of the character - a textured 3D body with humanoid bones - with five visemes, blinks, three emotions, and lookAt when the rig has eye bones. It takes 3-6 minutes and costs 25 API tokens ($2.50 to $3.75 depending on the pack), returned automatically if the conversion fails. The picture is checked before anything is charged: one that is not a whole, front-facing humanoid figure is refused with 422 picture_rejected, and fix=true has it redrawn first for 2 more tokens. The picture should show one whole character, standing, facing the camera, on a plain background.
One call, then poll
export RIGGLE_API_KEY=rgl_...
API=https://app.riggle3d.com/api/v1
# 1. send the picture (25 API tokens)
id=$(curl -s -X POST $API/conversions \
-H "Authorization: Bearer $RIGGLE_API_KEY" \
-H "Idempotency-Key: mascot-0001" \
-F image=@character.png \
-F name=mascot | jq -r .id)
# 2. poll: generating_model, then marking_face, building_vrm
until [ "$(curl -s $API/conversions/$id \
-H "Authorization: Bearer $RIGGLE_API_KEY" | jq -r .status)" != processing ]
do sleep 5; done
# 3. download the VRM
curl -s -o mascot.vrm $API/conversions/$id/vrm \
-H "Authorization: Bearer $RIGGLE_API_KEY"The only difference from a model conversion is the field: image instead of file. The conversion object comes back with input set to image and cost 25, and stage starts at generating_model. Everything else, including the errors, is in the API reference.
In Node 18 or later:
import { readFile } 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("image", new Blob([await readFile("character.png")]), "character.png");
// form.append("fix", "true"); // redraw it first if the check finds a problem (+2)
// form.append("force", "true"); // or skip the check
const res = await fetch(`${API}/conversions`, { method: "POST", headers, body: form });
const body = await res.json();
if (res.status === 422) console.log("picture rejected, nothing charged:", body.error.problems);
else if (res.status === 503) console.log("pictures are switched off right now");
else if (!res.ok) throw new Error(body.error.message);
else console.log(body.id, body.input, body.cost); // "image", 25Complete clients are in github.com/riggle3d/glb-to-vrm.
Which pictures work
The 3D model can only have what the picture shows, so the picture decides most of the result.
- One whole character. Head to toe in the frame. A portrait or a bust has no legs to rig, and two characters become one mesh.
- Standing. Upright, with the arms away from the body so they do not fuse with the torso.
- Facing the camera. A front view, not a side or three-quarter view.
- A plain background. Anything else in the frame, such as a floor, a shadow or a prop, can end up as part of the model.
- An open mouth helps. A character with its mouth open gives the most natural mouth shapes, and the 3D model keeps what the picture shows. A character drawn with closed lips still converts, with softer mouth movement.
.png or .jpg, up to 20 MB. The AI image to VRM guide has a reference prompt for generating a picture that meets all of this.
Rejected pictures: fix and force
Before anything is charged, the 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: no conversion is created, no tokens are taken, and the error carries a problems list, each entry with a code and a message.
| Problem code | What the check saw |
|---|---|
not_humanoid | Not a humanoid character |
multi_view | More than one view of the character in the picture, as on a character sheet |
not_full_body | Not the whole body, head to feet |
not_front | The character is not facing the camera |
From there you have three options:
- Send another picture.
fix=true. If the check finds a problem, the picture is redrawn as one full-body front view before the model is made. That is 2 API tokens on top of the 25, charged only when the picture is actually redrawn. You can set it on the first request, so a picture that needs it never comes back as a 422.force=true. Skip the check and use the picture as it is. It wins overfix: with both, nothing is checked or redrawn.
# check the picture, and redraw it first if the check finds a problem
# 25 API tokens if it passes, 27 if it had to be redrawn
curl -s -X POST $API/conversions \
-H "Authorization: Bearer $RIGGLE_API_KEY" \
-F image=@character.png \
-F fix=true
# skip the check and use the picture as it is (25 API tokens)
curl -s -X POST $API/conversions \
-H "Authorization: Bearer $RIGGLE_API_KEY" \
-F image=@character.png \
-F force=trueTo see the redrawn picture before you spend 25 tokens on it, do it in two steps. POST /pictures/fix starts the redraw on its own for 2 API tokens. It is a job like a conversion: poll GET /pictures/fix/{id} until status is succeeded, usually under a minute, then download GET /pictures/fix/{id}/image. Look at the PNG, and if it is right, send it to POST /conversions as image. Unlike fix=true, it always redraws, with no check first. The redrawn picture is kept for 7 days, and a fix that fails returns its tokens. The details are in the API reference.
# 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.pngThe 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 unchecked. A redrawn picture is a new drawing of your character, so look at the preview before you show the avatar to a user.
What stage tells you while you poll
generating_model: the 3D model is being made from the picture.rigging: shown only when the model needs a skeleton.marking_face: the mouth and eyes are being found.building_vrm: the VRM 1.0 is being finished.
The whole run takes 3-6 minutes. On success you get the VRM, a preview.mp4 playing every expression, stills, and warnings when something deserves a look. Generation from a picture varies more than conversion of a model you made, so play the preview before you show the avatar to a user.
Pricing
| Pack | API tokens | Price | Per picture → VRM |
|---|---|---|---|
| Starter | 100 | $15 | $3.75 |
| Builder | 500 | $60 | $3.00 |
| Scale | 2,500 | $250 | $2.50 |
A picture is 25 API tokens, which covers the 3D model and the VRM. With fix=true, a picture that had to be redrawn is 2 more: 27 tokens, which is $4.05, $3.24 or $2.70 by pack. A picture that passes the check is never charged the extra 2. The check itself runs before anything is charged, and if the conversion fails at any stage all of its tokens come back automatically, the 2 for the redraw included.
If POST /conversions answers 503 unavailable for an image, pictures are switched off for the moment; nothing is charged, and model conversions are not affected.
When to send a model instead
If you already have a 3D model of the character, from your own generator or from an artist, send the GLB: it is 10 tokens instead of 25, faster, and the body is exactly the one you made. See the GLB to VRM API. To do one picture by hand in the browser, use image to VRM.
Turn pictures into avatars from your own code
Make a key, buy a pack, and send your first picture. 25 API tokens a picture, returned if the conversion fails.
Get an API keyFAQ
How much does image to VRM cost through the API?
25 API tokens per picture: $3.75 with the Starter pack, $3.00 with Builder, $2.50 with Scale. That covers both the 3D model and the VRM, and it is returned if the conversion fails. A picture redrawn with fix=true is 2 tokens more.
How long does it take?
Three to six minutes. Poll GET /conversions/{id} every 3-5 seconds until status is succeeded or failed.
Which image formats and sizes are accepted?
.png and .jpg, up to 20 MB, uploaded as the multipart field image.
What does 422 picture_rejected mean?
The picture check found that the picture is not one whole humanoid character, head to feet, facing the camera. Nothing was created or charged. The problems list says why: not_humanoid, multi_view, not_full_body or not_front, each with a message. Send another picture, or the same one with fix=true or force=true.
What does fix=true do, and what does it cost?
If the picture check finds a problem, the picture is redrawn as one full-body front view before the 3D model is made. It adds 2 API tokens, 27 in all, and only when the picture is actually redrawn. A picture that passes the check costs the usual 25.
The check rejected a picture that I know is fine. What now?
Send it again with force=true. The check is advice and can be wrong about a usable picture; force skips it and uses the picture as it is.
Can I see the redrawn picture before the 3D model is made?
Yes. POST /pictures/fix starts a redraw on its own for 2 API tokens. Poll GET /pictures/fix/{id} until status is succeeded, usually under a minute, download the PNG from GET /pictures/fix/{id}/image, look at it, then send it to POST /conversions as image. With fix=true the check, the redraw and the conversion happen in one call and you first see the result in the preview. The standalone fix always redraws, and its tokens are returned if no picture comes back.
Can I use a portrait or a headshot?
No. The picture needs one whole character, standing and facing the camera. A VRM is a full humanoid, and a portrait has no body to rig.
Can I pass an image URL or a text prompt?
No. The API takes an uploaded .png or .jpg. Generate the picture with the image model of your choice, then upload it.
Can I download the intermediate 3D model?
The API returns the VRM, the preview video and the stills. A VRM is itself a binary glTF, so the same file opens as a GLB in tools that do not read the VRM extensions.
Are there free tokens to try it with?
No. There are no free API tokens: a key works once a pack is bought. A picture costs 25 tokens, and they are returned if the conversion fails.
What does 503 unavailable mean?
Pictures are switched off at the moment. Nothing was created or charged. Model conversions with the file field still work.
Can I use a photo of a real person?
Only with that person's consent, and expect less. The 3D step does best on stylised characters with clean shapes; the framing rules are the same.