Riggle VRM API — リファレンス
リグの有無を問わない3Dキャラクター、またはその画像を1つのREST APIに取り込むだけで、話したり瞬きしたりするVRM 1.0が返されます。このページは、認証、料金、全エンドポイント、変換オブジェクト、エラーなど、完全なリファレンスです。
Riggle VRM APIは、.glbまたは.vrm(リグの有無は問わず、100MBまで)、あるいはキャラクター1体の.png/.jpgを、ヒューマノイドボーン、5つの口形素(aa、ih、ee、oh、ou)、blink、blinkLeft、blinkRight、喜・怒・驚の表情、そして(リグに目のボーンがあれば)lookAtを備えたVRM 1.0に変換します。呼び出しは3回です。POST /conversions、GET /conversions/{id}を3〜5秒ごとにポーリング、そしてGET /conversions/{id}/vrm。モデルは10 APIトークン($1.00〜$1.50)、画像は25 APIトークンで、変換失敗時はトークンが自動的に返還されます。
クイックスタート
app.riggle3d.com/developersでキーを作成してください。APIトークンのパックを購入するとキーが有効になります。無料トークンはありません。次に以下を実行します:
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"リグ付きモデルは1〜3分、画像は3〜6分かかります。依存関係ゼロのPythonおよびNodeクライアントとしての同じフロー、およびその他のcurlサンプルはgithub.com/riggle3d/glb-to-vrmにあります。
基本と認証
- ベースURL:
https://app.riggle3d.com/api/v1 - 認証: すべてのリクエストに
Authorization: Bearer rgl_…を付与します。キーはデベロッパーページで作成および失効させます。シークレットは一度しか表示されないため、作成時に保管してください。 - リクエストは
multipart/form-data(アップロード時)またはボディなしです。レスポンスはファイルダウンロードを除きJSONです。 - すべて非同期です。 変換を作成し、
statusがsucceededまたはfailedになるまで3〜5秒ごとにポーリングしてから、ダウンロードします。 - 自動処理。 どのステップも人手を介する必要はありません。リグ付きモデル、リグなしモデル、画像はすべて同じ3回の呼び出しを経由します。
APIトークンと料金
APIは、それ自体の残高であるAPIトークンで支払われます。これらはデベロッパーページで購入し、有効期限はありません。これらはウェブアプリのStudioトークンとは異なります。どちらの種類も他方のアクションの支払いには使用できず、交換もできません。
| アクション | APIトークン |
|---|---|
モデル(.glb / .vrm、リグの有無は問わず)→ VRM | 10 |
画像(.png / .jpg)→ 3Dモデル → VRM | 25 |
…最初に画像を再描画する場合(fix=true、必要な場合のみ) | +2 |
画像単体の再描画(POST /pictures/fix) | 2 |
| ステータス、リスト、ダウンロード、プレビュー、削除 | 0 |
| パック | APIトークン | 価格 | モデルからのVRM単価 | 画像からのVRM単価 |
|---|---|---|---|---|
| スターター | 100 | $15 | $1.50 | $3.75 |
| ビルダー | 500 | $60 | $1.20 | $3.00 |
| スケール | 2,500 | $250 | $1.00 | $2.50 |
トークンは変換作成時に消費され、失敗した場合は自動的に返還されます。
エンドポイント
| メソッドとパス | 機能 |
|---|---|
POST /conversions | モデルまたは画像から変換を開始 |
GET /conversions/{id} | 1つの変換をポーリング |
GET /conversions?limit=20 | 最新の変換を新しい順に取得(最大100件) |
GET /conversions/{id}/vrm | VRMファイル |
GET /conversions/{id}/preview.mp4 | すべての表情を再生する動画 |
GET /conversions/{id}/preview/{name}.png | 1つの静止画 |
DELETE /conversions/{id} | 変換とそのファイルを削除 |
POST /pictures/fix | 画像単体の再描画を開始 |
GET /pictures/fix/{id} | 1つの再描画をポーリング |
GET /pictures/fix/{id}/image | 再描画されたPNG |
GET /account | トークン残高、料金、同時実行数制限 |
POST /conversions
マルチパートフィールド:
| フィールド | |
|---|---|
file | .glbまたは.vrm、100MBまで。リグ付きまたはリグなしのヒューマノイド。 |
image | fileの代わり:20MBまでの.pngまたは.jpg。1体のキャラクターが全身、立って、カメラを向いているもの。 |
name | 任意。変換に付ける名前。デフォルトはファイル名。 |
fix | 任意、画像のみ。true:画像チェックで問題が見つかった場合、モデル作成前に画像を全身正面図として再描画します。追加で2 APIトークン、再描画時のみ課金。 |
force | 任意、画像のみ。true:画像チェックをスキップし、画像をそのまま使用します。fixより優先:両方指定された場合、チェックも再描画も行われません。 |
画像チェック。 課金前に、画像が1体の完全なヒューマノイドキャラクター(頭から足まで、カメラ向き)であるかチェックされます。そうでない場合は422 picture_rejectedとproblemsリスト(not_humanoid、multi_view、not_full_body、not_front、各々にmessage付き)で拒否されます。別の画像を送信するか、同じものをfix=trueまたはforce=true付きで送信してください。チェックは助言であり、使用可能な画像について間違っている可能性もあります。そのためのforceです。チェックを実行できない場合、画像はそのまま通ります。
任意ヘッダーIdempotency-Key: <最大64文字の任意の文字列>でリトライが安全になります。同じキーでの2回目のリクエストは、新たに作成・課金する代わりに最初の変換を返します。
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=robot201と変換オブジェクトを返します。エラー:400 invalid_request、400 unsupported_file、401 unauthorized、402 insufficient_tokens、413 file_too_large、422 picture_rejected、429 too_many_active(アカウントごとに3つの変換が実行中)、503 unavailable(画像機能がオフ)。
GET /conversions/{id}
変換オブジェクトを返します。statusがprocessingでなくなるまで3〜5秒ごとに呼び出してください。
GET /conversions?limit=20
最新の変換を新しい順に取得。limitは最大100です。レスポンスは{"object": "list", "data": [conversion, …]}です。
GET /conversions/{id}/vrm
VRMファイル。statusがsucceededになるまで409 not_readyを返します。
GET /conversions/{id}/preview.mp4
すべての表情が再生される動画。VRMビューワーを開かずに結果を確認するために使用します。
GET /conversions/{id}/preview/{name}.png
1つの静止画。nameは変換オブジェクトのpreview_imagesのキーの1つです。
DELETE /conversions/{id}
204を返します。ファイルは1週間以内に完全に消去されます。実行中の変換を削除してもトークンは返還されません。
POST /pictures/fix
画像単体の再描画。マルチパートフィールドimage(20MBまでの.pngまたは.jpg)、任意のname、および任意のIdempotency-Keyヘッダー。画像を常に1体の全身正面図として無地の背景上に再描画します。事前のチェックはありません。2 APIトークンかかり、fix作成時に消費され、画像が返されない場合は返還されます。
これは変換と同様のジョブです。応答は201とpicture-fixオブジェクトで、その後ポーリングします。
{"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はprocessingからsucceededまたはfailedに変わります。fixは通常1分未満で完了します。3〜5秒ごとにポーリングしてください。失敗時、errorは{"code": "fix_failed", "message": "…"}で、refundedはtrueになります。成功時にimage_urlが設定されます。
エラー:400 invalid_request、400 unsupported_file、402 insufficient_tokens、413 file_too_large、429 too_many_active(アカウントごとに3つのfixが実行中、変換とは別にカウント)、503 unavailable。
GET /pictures/fix/{id}
picture-fixオブジェクトを返します。statusがprocessingでなくなるまで3〜5秒ごとに呼び出してください。
GET /pictures/fix/{id}/image
再描画されたPNG。statusがsucceededになるまで409 not_readyを返します。画像は7日間保持され、POST /conversionsにimageとして直接送信できます。
この例では、fixを最初から最後まで実行し、その結果を変換します。
# 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}変換オブジェクト
{
"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、その後succeededまたはfailed。stage(処理中):generating_model(画像のみ)、rigging(リグなしモデルのみ)、marking_face、building_vrm。変換終了後はnull。input:modelまたはimage。cost: 消費されたAPIトークン。refundedがtrueの場合、返還済み。error:null、または変換失敗時は{"code": "conversion_failed", "message": "…"}。その場合refundedはtrue。warnings: 文字列のリスト。アバターは構築されたが、プレビューを確認すべき点があることを示します(例:顔のマーキングの信頼性が低い、口形素がほとんど動かないなど)。vrm_url、preview_video_url、preview_images({name: url})は成功時に設定されます。これらは絶対API URLであり、同じAuthorizationヘッダーが必要なため、そのままブラウザに渡すことはできません。
エラー
すべてのエラーは、対応するHTTPステータスとともに同じ形式を取ります:
{"error": {"code": "not_ready", "message": "…"}}| コード | HTTP | 発生条件 |
|---|---|---|
invalid_request | 400 | リクエストがここで説明されている形式のいずれでもない |
unsupported_file | 400 | アップロードがエンドポイントで受け付けられないファイルタイプである |
unauthorized | 401 | Authorizationヘッダーに有効なキーがない |
insufficient_tokens | 402 | APIトークンが不足。error内にcodeと並んでrequiredとavailableが示される |
not_found | 404 | このアカウントに該当する変換がない |
not_ready | 409 | VRMまたは再描画された画像が、statusがsucceededになる前にリクエストされた |
file_too_large | 413 | モデルが100MB超、または画像が20MB超 |
picture_rejected | 422 | 画像が画像チェックを通過しなかった。problemsリストが付属し、課金はされない |
too_many_active | 429 | アカウントで3つの変換がすでに実行中、または3つの画像fixが実行中。両者は別々にカウントされる |
unavailable | 503 | 画像機能がオフになっている |
402は次のようになります:
{"error": {"code": "insufficient_tokens", "message": "…",
"required": 25, "available": 10}}そして422は:
{"error": {"code": "picture_rejected", "message": "…",
"problems": [{"code": "not_full_body", "message": "…"}]}}受け付けられた後に完了できなかった変換はHTTPエラーではありません。それはstatusがfailedの変換であり、error.codeがconversion_failedに設定され、トークンは返還されています。
Pythonのサンプル
requestsを使った3回の呼び出し:
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)依存関係が一切ないクライアントについては、サンプルリポジトリにあるものをコピーしてください。
Nodeのサンプル
Node 18以降、内蔵のfetch、FormData、Blobを使用。.mjsファイルとして保存してください:
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()));代わりに画像から開始するには、fileの代わりにimageフィールドを送信します。それ以降はすべて同じです。画像からVRMへのAPIページを参照してください。
出力内容
VRM 1.0ファイル。内容は以下の通りです:
- マッピングされたヒューマノイドボーン
- 5つの口形素:
aa、ih、ee、oh、ou blink、blinkLeft、blinkRighthappy、angry、surprised- リグに目のボーンがある場合はlookAt
顔の見た目の良さはモデルに依存します。口を開けてモデリングされたキャラクターは最も自然な口のシェイプになり、閉じた口はより穏やかな動きになります。結果が確認を要する場合、warningsがそれを知らせます。ファイルをユーザーに提供する前にpreview.mp4を再生してください。
出力はVRM 1.0のみです。52個のARKitブレンドシェイプは含まれません。
制限事項
- 入力:
.glbまたは.vrmは100MBまで、.pngまたは.jpgは20MBまで。ファイルはリクエスト内でアップロードされます。他の方法で渡すことはできません。 - 同時実行数: アカウントごとに3つの変換が実行可能。4つ目は
429 too_many_activeを受け取ります。いずれかが終了するまで待ってください。画像fixには、変換とは別にカウントされる独自の制限(3)があります。 - 時間: リグ付きモデルで1〜3分、画像で3〜6分。3〜5秒ごとにポーリングしてください。
- キャラクター: ヒューマノイド。画像の場合は、全身が写った、立った、正面向きのキャラクター1体。
- 削除された変換: ファイルは1週間以内に完全に消去されます。
タスク別ページ: GLBからVRMへのAPI、画像からVRMへのAPI、API経由でのVRMへの口形素と瞬きの追加。代わりにブラウザで1つのモデルを手動変換するには、GLBからVRMへのコンバーターを使用してください。
クリエイターからよくある質問
無料プランはありますか?
いいえ。無料のAPIトークンはありません。キーはパックを購入すると有効になります。パックは100トークン$15、500トークン$60、2,500トークン$250で、変換失敗時はトークンが自動的に返還されます。
変換が失敗した場合、トークンはどうなりますか?
自動的に返還されます。変換のステータスはfailedになり、error.codeはconversion_failed、refundedはtrueになります。唯一の例外は、実行中に削除した変換です。その場合、トークンは返還されません。
APIトークンはRiggleウェブアプリのトークンと同じですか?
いいえ。APIトークンはデベロッパーページで購入する別の残高です。ウェブアプリのStudioトークンはAPI呼び出しの支払いには使えず、APIトークンはウェブアプリでのダウンロードの支払いには使えません。また、両者を交換することもできません。
APIトークンに有効期限はありますか?
いいえ。
Webhookはありますか?
いいえ。APIはポーリング方式です。GET /conversions/{id}を3〜5秒ごとに呼び出し、ステータスがsucceededまたはfailedになるまで確認してください。
SDKはありますか?
インストールするパッケージはありません。github.com/riggle3d/glb-to-vrmのサンプルリポジトリに、プロジェクトにコピーできる依存関係ゼロのPythonクライアント、Nodeクライアント、curlのサンプルがあります。
ファイルをアップロードする代わりにURLを渡せますか?
いいえ。モデルまたは画像は、POST /conversionsリクエストでmultipart/form-dataとしてアップロードされます。
FBXを送信できますか?
いいえ。APIが受け付けるのは、モデルは.glbと.vrm、画像は.pngと.jpgです。Blenderなどから、まずFBXをバイナリglTF(.glb)にエクスポートしてください。
画像が利用できない場合はどうなりますか?
画像は課金前にチェックされます。キャラクター1体が全身、正面向きで写っていない場合、リクエストは422 picture_rejectedと問題のリストを返します。別の画像を送信するか、fix=trueを追加して最初に全身正面図に再描画させる(追加で2 APIトークン、再描画時のみ課金)、またはforce=trueを追加してチェックをスキップしてください。
一度にいくつの変換を実行できますか?
アカウントごとに3つです。4つ目のPOST /conversionsは、いずれかが終了するまで429 too_many_activeを返します。
結果が良いかどうかはどうやってわかりますか?
変換オブジェクトのwarningsを読み、preview.mp4を再生してください。警告は、アバターは構築されたものの、例えば顔の検出の信頼度が低い、または口形素がほとんど動かないなど、確認すべき点があることを意味します。
モデルはリグ済みである必要がありますか?
いいえ。リグなしのヒューマノイド.glbも機能します。Riggleがスケルトンを追加し、その間stageはriggingと表示されます。コストは同じ10 APIトークンで、同じVRM 1.0が出力されます。