Riggle VRM API — リファレンス

リグの有無を問わない3Dキャラクター、またはその画像を1つのREST APIに取り込むだけで、話したり瞬きしたりするVRM 1.0が返されます。このページは、認証、料金、全エンドポイント、変換オブジェクト、エラーなど、完全なリファレンスです。

APIキーを取得する モデル1体$1から・.glb、.vrm、.png、.jpgを入力・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、リグの有無は問わず)→ VRM10
画像(.png / .jpg)→ 3Dモデル → VRM25
…最初に画像を再描画する場合(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}/vrmVRMファイル
GET /conversions/{id}/preview.mp4すべての表情を再生する動画
GET /conversions/{id}/preview/{name}.png1つの静止画
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まで。リグ付きまたはリグなしのヒューマノイド。
imagefileの代わり: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=robot

201と変換オブジェクトを返します。エラー: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.png

GET /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_request400リクエストがここで説明されている形式のいずれでもない
unsupported_file400アップロードがエンドポイントで受け付けられないファイルタイプである
unauthorized401Authorizationヘッダーに有効なキーがない
insufficient_tokens402APIトークンが不足。error内にcodeと並んでrequiredとavailableが示される
not_found404このアカウントに該当する変換がない
not_ready409VRMまたは再描画された画像が、statusがsucceededになる前にリクエストされた
file_too_large413モデルが100MB超、または画像が20MB超
picture_rejected422画像が画像チェックを通過しなかった。problemsリストが付属し、課金はされない
too_many_active429アカウントで3つの変換がすでに実行中、または3つの画像fixが実行中。両者は別々にカウントされる
unavailable503画像機能がオフになっている

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、blinkRight
  • happy、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から。変換に失敗した場合はトークンが返還されます。

APIキーを取得する

クリエイターからよくある質問

無料プランはありますか?

いいえ。無料の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が出力されます。

ガイド