Add visemes and blinks to a VRM via API — a frozen face in, a talking one out
Lip sync on a VRM only works if the file has the five viseme expressions to drive. Most converted and AI-generated avatars do not. This API builds them, with blinks and emotions, and hands the VRM back.
To add visemes and blinks to a VRM through an API, POST the .vrm (or a rigged .glb) as the field file to https://app.riggle3d.com/api/v1/conversions, poll GET /conversions/{id}, and download GET /conversions/{id}/vrm. You get back a VRM 1.0 with the visemes aa, ih, ee, oh and ou, blink, blinkLeft, blinkRight, happy, angry, surprised, and lookAt when the rig has eye bones, in 1-3 minutes, with no person in the loop. It costs 10 API tokens ($1.00 to $1.50), returned if the conversion fails. The API builds the shapes; your app or its lip-sync library drives them from audio.
Send the VRM, get the VRM back
export RIGGLE_API_KEY=rgl_...
API=https://app.riggle3d.com/api/v1
# 1. send the VRM whose face does not move (10 API tokens)
id=$(curl -s -X POST $API/conversions \
-H "Authorization: Bearer $RIGGLE_API_KEY" \
-F file=@avatar.vrm | 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. the VRM, and a video of every expression to check it by
curl -s -o avatar-talking.vrm $API/conversions/$id/vrm \
-H "Authorization: Bearer $RIGGLE_API_KEY"
curl -s -o preview.mp4 $API/conversions/$id/preview.mp4 \
-H "Authorization: Bearer $RIGGLE_API_KEY"A .vrm and a .glb go through the same endpoint and the same field. The full contract is in the API reference; ready-made Python and Node clients are in github.com/riggle3d/glb-to-vrm.
What is added
| Expression | What drives it |
|---|---|
aa ih ee oh ou | Lip sync: the five vowel shapes a VRM app blends between as audio plays |
blink blinkLeft blinkRight | Idle blinking, winks, eye tracking |
happy angry surprised | Reactions: an emotion tag from your LLM, a hotkey, a tracked face |
| lookAt | The eyes following a target or the camera. Included when the rig has eye bones |
These are the VRM 1.0 preset names, so anything that drives VRM expressions by name finds them without configuration.
Not included: the 52 ARKit blendshapes used for iPhone "perfect sync" face tracking. That is a different job.
What needs these expressions
- three-vrm and web apps.
vrm.expressionManager.setValue('aa', v)does nothing visible on a file with noaaexpression. With one, a volume- or phoneme-driven lip sync is a few lines. - AI companions and TTS-driven avatars. A character that speaks model output needs the five vowels to follow the audio, a blink so it does not stare, and an emotion or two to react with.
- VTuber apps. Tracking and microphone lip sync in the style of VSeeFace map onto the same vowel and blink expressions. Check that your app reads VRM 1.0: some desktop apps still only read VRM 0.x.
- VRChat-style viseme lip sync. Pipelines that expect a mouth shape per sound start from the same thing: a mesh that has those shapes at all.
The usual symptom of a file without them: the avatar loads, moves its body, and its mouth stays shut while it speaks. Why a VRM's mouth does not move covers the causes.
What decides the quality
The mouth shapes follow the mouth your model already has, so the model matters more than anything else.
- A mouth modelled open gives the most natural mouth shapes.
- A closed mouth still converts, with softer mouth movement.
- A face that is hard to make out still converts, with a warning.
That is what warnings is for. An empty list means nothing looked off. Otherwise fetch preview.mp4 or the stills in preview_images and look before you put the avatar in front of a user.
Pricing
10 API tokens per VRM: $1.50 with the Starter pack (100 tokens, $15), $1.20 with Builder (500, $60), $1.00 with Scale (2,500, $250). Polling, downloads and previews are free, tokens do not expire, and a failed conversion returns its tokens automatically. There are no free API tokens: a key works once a pack is bought.
Doing one avatar by hand? Add visemes and blinks to a VRM in the browser. Starting from a GLB that is not a VRM yet? It is the same call: see the GLB to VRM API. Starting from a picture? See the image to VRM API.
Give your avatars a face that moves
Make a key and buy a pack: 10 API tokens a VRM, returned if the conversion fails.
Get an API keyFAQ
Does the API do the lip sync itself?
It builds what lip sync needs: the aa, ih, ee, oh and ou expressions on the avatar. Driving them from audio or from TTS phonemes happens in your app, with three-vrm's expression manager or whichever lip-sync library you use.
Can I send a VRM that already exists?
Yes. Upload the .vrm as the field file. You get back a VRM 1.0 with the visemes, blinks, emotions, and lookAt when the rig has eye bones.
Can I send a rigged GLB instead of a VRM?
Yes. A .glb goes through the same endpoint and comes back as a VRM 1.0 with the same expression set. An unrigged GLB works too.
Does it add ARKit blendshapes or perfect sync?
No. The output has the VRM 1.0 expression set: five visemes, blink, blinkLeft, blinkRight, happy, angry, surprised, and lookAt when the rig has eye bones. The 52 ARKit shapes are not part of it.
Which viseme names does it use?
The VRM 1.0 presets: aa, ih, ee, oh, ou. Code that sets VRM expressions by preset name works without any mapping.
My model's mouth is closed. Will it still work?
Yes. A closed-mouth model converts too; its mouth movement is softer than on a model whose mouth was modelled open, so check the preview.
How do I check the result without opening a viewer?
Download GET /conversions/{id}/preview.mp4, which plays every expression, or the stills listed in preview_images. Both need the same Authorization header as every other call.
How much does it cost?
10 API tokens per VRM, between $1.00 and $1.50 depending on the pack. If the conversion fails the tokens are returned automatically.
Is the output VRM 0.x or 1.0?
VRM 1.0 only.