画像→VRM変換API — 画像を送ると、話せるVRM 1.0が返る

1回のリクエストでキャラクターのPNGまたはJPGから、会話や瞬きをするVRM 1.0が生成されます。3Dジェネレーター、自動リギングツール、コンバーターを自前で連携させる必要はありません。

APIキーを取得 画像1枚につき25 APIトークン・.pngまたは.jpgは最大20MB・VRM 1.0を出力

APIで画像をVRMに変換するには、.pngまたは.jpg(最大20MB)をimageフィールドとしてhttps://app.riggle3d.com/api/v1/conversionsにPOSTします。返されるのは、キャラクターのVRM 1.0です。これは、テクスチャ付きの3Dボディに人型ボーンが設定され、5種類の口パク、瞬き、3種類の感情表現、そしてリグに目ボーンがある場合はlookAt機能を持ちます。処理には3~6分かかり、料金は25 APIトークン(パックに応じて2.50ドルから3.75ドル)で、変換に失敗した場合は自動的に返却されます。課金前に画像がチェックされ、全身が写った正面向きの人型でない場合は422 picture_rejectedで拒否されます。fix=trueを指定すると、追加2トークンで画像が先に再描画されます。画像は、無地の背景に、キャラクター1体の全身が、立った状態で正面を向いて写っている必要があります。

1回のコールと、その後のポーリング

export RIGGLE_API_KEY=rgl_...
API=https://app.riggle3d.com/api/v1

# 1. 画像を送信(25 APIトークン)
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. ポーリング: generating_model、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. VRMをダウンロード
curl -s -o mascot.vrm $API/conversions/$id/vrm \
  -H "Authorization: Bearer $RIGGLE_API_KEY"

モデルからの変換との唯一の違いは、フィールドがfileではなくimageである点です。変換オブジェクトはinputがimage、costが25に設定されて返され、stageはgenerating_modelから始まります。エラーを含むその他すべての詳細は、APIリファレンスに記載されています。

Node 18以降の場合:

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");   // チェックで問題が見つかった場合に先に再描画(+2トークン)
// form.append("force", "true"); // またはチェックをスキップ

const res = await fetch(`${API}/conversions`, { method: "POST", headers, body: form });
const body = await res.json();
if (res.status === 422) console.log("画像が拒否されました、課金はありません:", body.error.problems);
else if (res.status === 503) console.log("現在、画像からの変換は停止しています");
else if (!res.ok) throw new Error(body.error.message);
else console.log(body.id, body.input, body.cost); // "image", 25

完成版のクライアントはgithub.com/riggle3d/glb-to-vrmでご覧いただけます。

どのような画像が有効か

3Dモデルは画像に写っているものしか再現できないため、最終的な結果の大部分は元の画像によって決まります。

  • キャラクター1体の全身。 フレーム内に頭からつま先まで収まっていること。ポートレートやバストアップではリギングする脚がなく、2人のキャラクターは1つのメッシュになってしまいます。
  • 立った状態。 直立し、腕が胴体から離れていること。胴体と融合してしまうのを防ぎます。
  • カメラに正面向き。 横向きや斜め向きではなく、正面からのビューであること。
  • 無地の背景。 床、影、小道具など、フレーム内に他のものが写っていると、モデルの一部になってしまう可能性があります。
  • 口が開いているとより良い。 口を開けているキャラクターは最も自然な口の形になり、3Dモデルは画像に写っている状態を維持します。唇を閉じて描かれたキャラクターも変換できますが、口の動きはよりソフトになります。

.pngまたは.jpg形式で、最大20MBまで。これらすべての条件を満たす画像を生成するための参照プロンプトは、AI画像からVRMアバターを生成するガイドでご覧いただけます。

拒否された画像:fixとforceオプション

課金が行われる前に、画像が頭から足まで全身が写った正面向きの人型キャラクターであるかがチェックされます。そうでない画像は422 picture_rejectedで拒否されます。この場合、変換は作成されず、トークンも消費されません。エラーには、コードとmessageを持つ各エントリが含まれるproblemsリストが付随します。

問題コードチェックで検出された内容
not_humanoid人型のキャラクターではない
multi_viewキャラクターシートのように、1枚の画像に複数のビューが含まれている
not_full_body頭から足までの全身が写っていない
not_frontキャラクターがカメラに正面を向いていない

そこから3つの選択肢があります。

  • 別の画像を送信する。
  • fix=true。 チェックで問題が見つかった場合、モデルが作成される前に、画像が全身正面向きのビューとして再描画されます。これには25トークンに加えて2 APIトークンがかかり、実際に画像が再描画された場合にのみ課金されます。最初のリクエストでこれを設定すれば、修正が必要な画像が422エラーで返ってくることはありません。
  • force=true。 チェックをスキップして、画像をそのまま使用します。これはfixよりも優先されます。両方が指定された場合、何もチェックまたは再描画されません。
# 画像をチェックし、問題が見つかった場合は先に再描画
# チェックを通過すれば25 APIトークン、再描画が必要だった場合は27 APIトークン
curl -s -X POST $API/conversions \
  -H "Authorization: Bearer $RIGGLE_API_KEY" \
  -F image=@character.png \
  -F fix=true

# チェックをスキップして画像をそのまま使用(25 APIトークン)
curl -s -X POST $API/conversions \
  -H "Authorization: Bearer $RIGGLE_API_KEY" \
  -F image=@character.png \
  -F force=true

25トークンを費やす前に再描画された画像を確認したい場合は、2つのステップで行います。POST /pictures/fixは、2 APIトークンで再描画のみを開始します。これは変換と同様のジョブです。statusがsucceededになるまでGET /pictures/fix/{id}をポーリングし(通常1分未満)、その後GET /pictures/fix/{id}/imageからダウンロードします。PNGを確認し、問題がなければそれをimageとしてPOST /conversionsに送信します。fix=trueとは異なり、この方法は常に再描画を行い、事前のチェックはありません。再描画された画像は7日間保持され、修正に失敗した場合はトークンが返却されます。詳細はAPIリファレンスに記載されています。

# 1. 再描画を開始(2 APIトークン)
fix=$(curl -s -X POST $API/pictures/fix \
  -H "Authorization: Bearer $RIGGLE_API_KEY" \
  -F image=@character.png | jq -r .id)

# 2. 処理が完了するまでポーリング
until [ "$(curl -s $API/pictures/fix/$fix \
  -H "Authorization: Bearer $RIGGLE_API_KEY" | jq -r .status)" != processing ]
do sleep 4; done

# 3. 再描画されたPNGをダウンロードして確認
curl -s -o fixed.png $API/pictures/fix/$fix/image \
  -H "Authorization: Bearer $RIGGLE_API_KEY"

# 4. 他の画像と同様に送信(25 APIトークン)
curl -s -X POST $API/conversions \
  -H "Authorization: Bearer $RIGGLE_API_KEY" \
  -F image=@fixed.png

このチェックはあくまで助言です。使用可能な画像について間違っている可能性もあり、そのためのforceオプションです。また、チェックが実行できない場合は、画像はチェックなしで処理されます。再描画された画像はキャラクターの新しい絵になるため、ユーザーにアバターを見せる前にプレビューを確認してください。

ポーリング中にstageが示す内容

  1. generating_model: 画像から3Dモデルが作成されています。
  2. rigging: モデルにスケルトンが必要な場合にのみ表示されます。
  3. marking_face: 口と目が検出されています。
  4. building_vrm: VRM 1.0の仕上げが行われています。

全体の処理には3~6分かかります。成功すると、VRM、すべての表情を再生するpreview.mp4、静止画、そして確認すべき点がある場合のwarningsが取得できます。画像からの生成は、自作モデルの変換よりもばらつきが大きいため、ユーザーにアバターを見せる前にプレビューを再生して確認してください。

料金

パックAPIトークン数価格画像→VRMあたりの料金
スターター100$15$3.75
ビルダー500$60$3.00
スケール2,500$250$2.50

画像1枚あたり25 APIトークンで、3DモデルとVRMの両方の生成が含まれます。fix=trueを使用し、再描画が必要だった画像はさらに2トークン、合計27トークン(パックに応じて4.05ドル、3.24ドル、または2.70ドル)かかります。チェックを通過した画像に追加の2トークンが課金されることはありません。チェック自体は課金前に行われ、どの段階で変換が失敗しても、再描画のための2トークンを含め、すべてのトークンが自動的に返却されます。

画像に対してPOST /conversionsが503 unavailableを返した場合、現在画像からの変換は一時的に停止しています。課金はされず、モデルからの変換には影響ありません。

代わりにモデルを送信すべき場合

自社のジェネレーターやアーティストから入手したキャラクターの3Dモデルを既にお持ちの場合は、GLBを送信してください。25トークンではなく10トークンで済み、処理も速く、作成した通りのボディが得られます。GLB to VRM APIをご覧ください。ブラウザで1枚の画像を手動で処理する場合は、Image to VRMをご利用ください。

自社のコードから画像をアバターに変換

キーを作成し、パックを購入して、最初の画像を送信しましょう。画像1枚につき25 APIトークンで、変換に失敗した場合は返却されます。

APIキーを取得

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

API経由でのImage to VRMの料金はいくらですか?

画像1枚あたり25 APIトークンです。スターターパックでは3.75ドル、ビルダーパックでは3.00ドル、スケールパックでは2.50ドルになります。これには3DモデルとVRMの両方の生成が含まれ、変換に失敗した場合は返却されます。fix=trueで再描画された画像は、さらに2トークンかかります。

処理にはどのくらい時間がかかりますか?

3~6分です。statusがsucceededまたはfailedになるまで、3~5秒ごとにGET /conversions/{id}をポーリングしてください。

どの画像形式とサイズが受け付けられますか?

.pngと.jpg形式で、最大20MBまで。マルチパートフィールドimageとしてアップロードしてください。

422 picture_rejectedとはどういう意味ですか?

画像チェックで、画像が全身が写った正面向きの人型キャラクターではないと判断されたことを意味します。変換は作成されず、課金もされませんでした。problemsリストに、not_humanoid、multi_view、not_full_body、not_frontといった理由がメッセージと共に示されます。別の画像を送信するか、同じ画像をfix=trueまたはforce=true付きで再送信してください。

fix=trueは何をするもので、料金はいくらですか?

画像チェックで問題が見つかった場合、3Dモデルが作成される前に、画像が全身正面向きのビューとして再描画されます。これによりAPIトークンが2つ追加され、合計27トークンになりますが、これは実際に画像が再描画された場合にのみ課金されます。チェックを通過した画像は、通常通りの25トークンです。

問題ないはずの画像がチェックで拒否されました。どうすればよいですか?

force=trueを付けて再送信してください。チェックは助言であり、使用可能な画像について間違うこともあります。forceはチェックをスキップし、画像をそのまま使用します。

3Dモデルが作成される前に、再描画された画像を確認できますか?

はい。POST /pictures/fixは2 APIトークンで再描画のみを開始します。statusがsucceededになるまでGET /pictures/fix/{id}をポーリングし(通常1分未満)、GET /pictures/fix/{id}/imageからPNGをダウンロードして確認し、その後imageとしてPOST /conversionsに送信します。fix=trueを使うと、チェック、再描画、変換が1回のコールで行われ、結果はプレビューで初めて確認できます。スタンドアロンのfixは常に再描画を行い、画像が返されない場合はトークンが返却されます。

ポートレートや顔写真を使えますか?

いいえ。画像には、立った状態でカメラに正面を向いたキャラクター1体の全身が写っている必要があります。VRMは完全な人型であり、ポートレートにはリギングする体がありません。

画像URLやテキストプロンプトを渡せますか?

いいえ。APIはアップロードされた.pngまたは.jpgを受け付けます。お好きな画像モデルで画像を生成し、その後アップロードしてください。

中間生成物の3Dモデルをダウンロードできますか?

APIはVRM、プレビュー動画、静止画を返します。VRM自体がバイナリglTFなので、VRM拡張を読み込まないツールでは、同じファイルがGLBとして開きます。

試用できる無料トークンはありますか?

いいえ。無料のAPIトークンはありません。APIキーはパックを購入すると有効になります。画像1枚あたり25トークンかかり、変換に失敗した場合は返却されます。

503 unavailableとはどういう意味ですか?

現在、画像からの変換は一時的に停止しています。変換は作成されず、課金もされませんでした。fileフィールドを使用するモデルからの変換は引き続き機能します。

実在の人物の写真を使えますか?

その人物の同意がある場合にのみ可能です。また、期待する結果は得られにくいでしょう。3D化のステップは、クリーンな形状を持つ様式化されたキャラクターで最も良い結果を出します。フレーミングのルールは同じです。

ガイド