Creative Lab — フィギュア API
元となる写真を、ちびキャラ風のコレクタブル3Dフィギュアへと2段階で変換します。
prototype(プロトタイプ)ステージでは、入力写真からスタイル適用済みのコンセプト画像を生成し、続く
build(ビルド)ステージでは、そのコンセプト画像をテクスチャ付きの3Dモデルへと変換します。この2つのステージは
input_task_id によって紐付けられます。
POST /openapi/creative-lab/figure/v1/prototypePOST /openapi/creative-lab/figure/v1/build
フィギュアプロトタイプタスクを作成する
元の写真から、単一のちびキャラ風コンセプト画像を生成します。返却されるタスクIDは、build エンドポイントに input_task_id として渡すものです。レスポンスの形式については
フィギュアプロトタイプタスクオブジェクト
を参照してください。
パラメータ
- Name
- image_url
- Type
- string
- 必須
- Description
Meshy がちびキャラフィギュア風にスタイライズする元の写真です。現在サポートしている形式は
.jpg、.jpeg、.png、.webpです。画像を指定する方法は2通りあります:
- 公開アクセス可能なURL: パブリックインターネットからアクセス可能なURL。
- Data URI: 画像をbase64エンコードしたdata URI。Data URIの例:
data:image/jpeg;base64,<your base64-encoded image data>。
- Name
- name
- Type
- string
- Description
表示用のオプションのタスク名です。最大100文字まで。
- Name
- remove_background
- Type
- boolean
- デフォルト false
- Description
trueに設定すると、プロトタイプ画像は背景が除去された透明RGBA PNGとして返され、被写体を任意の背景に合成できます。
戻り値
レスポンスの result プロパティには、新しく作成されたフィギュアプロトタイプタスクのタスク id が含まれます。タスクの取得 エンドポイントをポーリングするか、ストリーム を購読して、タスクが SUCCEEDED に達するのを待ってから、そのIDを build エンドポイント に input_task_id として渡してください。
失敗モード
- Name
400 - Bad Request- Description
リクエストが受理できませんでした。一般的な原因:
- パラメータの欠落:
image_urlは必須です。 - 無効な画像形式: 指定された
image_urlがサポート対象の形式(.jpg、.jpeg、.png、.webp)ではありません。 - 画像サイズが範囲外: 画像が小さすぎるか、最大ファイルサイズを超えているか、最大ピクセル数を超えています。
- 到達不能なURL:
image_urlをダウンロードできませんでした(404またはtimeout)。 - 無効なData URI: base64文字列の形式が不正です。
- コンテンツがフラグ対象: 入力画像がNSFWまたは知的財産のmoderationによってフラグ付けされました。
- パラメータの欠落:
- Name
401 - Unauthorized- Description
認証に失敗しました。APIキーを確認してください。
- Name
402 - Payment Required- Description
このタスクを実行するためのクレジットが不足しています。
- Name
429 - Too Many Requests- Description
レート制限を超過しました。
Request
# Stage 1: generate a chibi-style concept image
curl https://api.meshy.ai/openapi/creative-lab/figure/v1/prototype \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"image_url": "<your publicly accessible image url or base64-encoded data URI>"
}'
Response
{
"result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}


フィギュアビルドタスクを作成する
成功したプロトタイプタスクから、最終的なテクスチャ付き3Dフィギュアを生成します。 このビルドは画像から3Dと同じ画像から3Dへのパイプラインで実行されるため、 レスポンスオブジェクトの形式と出力URLのリストは完全に一致します。 レスポンスの形状についてはフィギュアビルドタスクオブジェクトを参照してください。
パラメータ
- Name
- input_task_id
- Type
- string
- 必須
- Description
同じOpenAPIエンドポイントを通じて作成されたプロトタイプタスクのタスクID。プロトタイプは同じAPIキーで作成されている必要があり、
SUCCEEDEDに達していて、かつ候補画像をちょうど1つ生成している必要があります。webapp経由で作成されたプロトタイプタスクは受け付けられません——buildエンドポイントは
POST /openapi/creative-lab/figure/v1/prototypeによって生成されたプロトタイプタスクのみを受け付け、それ以外のソースは404で拒否します。
- Name
- name
- Type
- string
- Description
表示用のオプションのタスク名。最大100文字。
戻り値
レスポンスのresultプロパティには、新しく作成されたフィギュアビルドタスクのタスクidが含まれます。タスクを取得するエンドポイントをポーリングするか、ストリームを購読して、タスクがSUCCEEDEDに達するまで待機し、その後model_urls.glbからテクスチャ付きGLBをダウンロードしてください(ダウンストリームのパイプラインがOBJを好む場合は、model_urls.objとmodel_urls.mtlからOBJ + MTLのペアをダウンロードすることもできます)。
失敗モード
- Name
400 - Bad Request- Description
リクエストが受け入れられませんでした。一般的な原因は以下の通りです:
- パラメータ不足:
input_task_idが必須です。 - 無効なUUID:
input_task_idが有効なUUIDではありません。 - 親タスクが未成功:参照されているプロトタイプタスクがまだ
SUCCEEDEDに達していません。 - 候補なし:プロトタイプタスクは成功しましたが、候補画像を生成していません。
- パラメータ不足:
- Name
401 - Unauthorized- Description
認証に失敗しました。APIキーを確認してください。
- Name
402 - Payment Required- Description
このタスクを実行するためのクレジットが不足しています。
- Name
404 - Not Found- Description
参照されているプロトタイプタスクが存在しないか、別のユーザーに属しているか、webapp経由で作成されたものです(build にチェーンできるのはAPIモードのプロトタイプタスクのみです)。
- Name
429 - Too Many Requests- Description
レート制限を超えました。
Request
# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/figure/v1/build \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578"
}'
Response
{
"result": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb"
}

フィギュアタスクの取得
有効なタスク id を指定して、prototype タスクまたは build タスクを取得します。URL パスは
タスクのステージと一致している必要があります — build タスクを
/prototype/:id 経由で取得すると 404 が返され、逆の場合も同様です。
レスポンスの形式については、The Figure Prototype Task Object および The Figure Build Task Object を参照してください。
パラメータ
- Name
- id
- Type
- path
- Description
取得対象のフィギュアタスクの一意の識別子。
戻り値
レスポンスにはフィギュアタスクオブジェクトが含まれます。その形式は、 どのステージがリクエストされたかによって異なります。
Request
# Prototype
curl https://api.meshy.ai/openapi/creative-lab/figure/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
# Build
curl https://api.meshy.ai/openapi/creative-lab/figure/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Prototype Response
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "creative-lab-figure-prototype",
"name": "",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1729123456000,
"started_at": 1729123460000,
"finished_at": 1729123486000,
"expires_at": 1729382686000,
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 6,
"image_urls": [
"https://assets.meshy.ai/***/concept.png?Expires=***"
]
}
Build Response
{
"id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
"type": "creative-lab-figure-build",
"name": "",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1729123500000,
"started_at": 1729123510000,
"finished_at": 1729123535000,
"expires_at": 1729382735000,
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 20,
"prompt": "",
"negative_prompt": "",
"texture_prompt": "",
"texture_image_url": "",
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***",
"obj": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.obj?Expires=***",
"mtl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.mtl?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/preview.png?Expires=***",
"texture_urls": [
{
"base_color": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/texture_0.png?Expires=***"
}
]
}
フィギュアタスクを削除する
フィギュアタスクをキャンセルします。タスクがまだ PENDING の場合、作成時に
消費されたクレジットは返金されます。すでに IN_PROGRESS のタスクは、
返金なしでキャンセルされます(ワーカーがすでにリソースを消費している可能性があるため)。
すでに終了状態(SUCCEEDED、FAILED、CANCELED)に達しているタスクは
キャンセルできません。
URLパスはタスクのステージと一致している必要があります —
/prototype/:buildId に対する DELETE は 404 を返します。
パスパラメータ
- Name
- id
- Type
- path
- Description
キャンセルするフィギュアタスクの一意の識別子。
戻り値
成功時には空のボディとともに 204 No Content を返します。
失敗モード
- Name
400 - Bad Request- Description
タスクはすでに終了状態にあり、キャンセルできません。
- Name
404 - Not Found- Description
タスクが存在しないか、別のユーザーに属しているか、そのステージがURLパスと一致していません。
Request
curl --request DELETE \
--url https://api.meshy.ai/openapi/creative-lab/figure/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
// Returns 204 No Content on success (empty body).
フィギュアタスクをストリーム
フィギュアタスクのリアルタイム更新を、Server-Sent Events (SSE) を介してストリーム配信します。
URLパスはタスクのステージと一致している必要があります。/prototype/:buildId/stream
でストリームを開くと、status_code: 404 を伴う単一の event: error ペイロードが送出され、ストリームは閉じられます。
パラメータ
- Name
- id
- Type
- path
- Description
ストリーム配信するフィギュアタスクの一意な識別子です。
戻り値
Figure Prototype
または Figure Build タスクオブジェクトのストリームを
Server-Sent Events として返します。各フレームには、そのステージの完全なタスクオブジェクトが含まれます — これは
Get エンドポイントが返すものと同じ形状です。そのため、タスクが PENDING または IN_PROGRESS の間は、
出力フィールドはまだ値が設定されておらず(null、[]、または {})、
finished_at は null になります。
Request
curl -N https://api.meshy.ai/openapi/creative-lab/figure/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response Stream
// Error event example (wrong stage or task not found)
event: error
data: {
"status_code": 404,
"message": "Task not found"
}
// Message event examples illustrate task progress.
// Every frame is the full task object; fields not yet populated are null / empty.
// The PENDING frame below is abbreviated to the fields that change.
event: message
data: {
"id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
"progress": 0,
"status": "PENDING"
}
event: message
data: {
"id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
"type": "creative-lab-figure-build",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1729123500000,
"started_at": 1729123510000,
"finished_at": 1729123535000,
"expires_at": 1729382735000,
"task_error": null,
"consumed_credits": 20,
"prompt": "",
"negative_prompt": "",
"texture_prompt": "",
"texture_image_url": "",
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***",
"obj": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.obj?Expires=***",
"mtl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.mtl?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/preview.png?Expires=***",
"texture_urls": [
{
"base_color": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/texture_0.png?Expires=***"
}
]
}
List Figure Tasks
単一のステージに関するフィギュアタスクのページネーションされた一覧を取得します。URLパス
がステージを選択します — /prototype はプロトタイプタスクを返し、/build
はビルドタスクを返します。もう一方のステージのタスクは、どちらのレスポンスにも含まれません。
Path Parameters
- Name
- stage
- Type
- path
- 必須
- Description
prototypeまたはbuildのいずれかです。このコレクションは、URLに一致する ステージのタスクのみを返します —/prototypeを取得してもビルドタスクが 返されることはなく、その逆も同様です。
Query Parameters
- Name
- page_num
- Type
- integer
- デフォルト 1
- Description
ページネーション用のページ番号です。
- Name
- page_size
- Type
- integer
- デフォルト 10
- Description
ページサイズの上限です。最大は
100件まで指定できます。
- Name
- sort_by
- Type
- string
- デフォルト -created_at
- Description
並び替えに使用するフィールドです。利用可能な値:
+created_at: 作成日時の昇順で並び替えます。-created_at: 作成日時の降順で並び替えます。
Returns
ステージごとのタスクオブジェクトのページネーションされた一覧を返します — /prototype
を一覧取得する場合は
フィギュアプロトタイプタスクオブジェクト、
/build を一覧取得する場合は
フィギュアビルドタスクオブジェクト です。
Request
# List prototype tasks
curl https://api.meshy.ai/openapi/creative-lab/figure/v1/prototype?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
# List build tasks
curl https://api.meshy.ai/openapi/creative-lab/figure/v1/build?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response (List Prototype Tasks)
[
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "creative-lab-figure-prototype",
"name": "",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1729123456000,
"started_at": 1729123460000,
"finished_at": 1729123486000,
"expires_at": 1729382686000,
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 6,
"image_urls": [
"https://assets.meshy.ai/***/concept.png?Expires=***"
]
}
]
The Figure Prototype Task Object
Figure Prototype Task オブジェクトは、元となる写真からちびキャラ風のコンセプト画像を生成するために Meshy が追跡する作業単位です。この段階の出力は input_task_id を介してビルド段階へと連結されます。
プロパティ
- Name
- id
- Type
- string
- Description
タスクの一意の識別子です。実装の詳細としてタスク ID には k-sortable な UUID を使用していますが、id のフォーマットについていかなる前提も置くべきではありません。
- Name
- type
- Type
- string
- Description
タスクのタイプです。値は
creative-lab-figure-prototypeです。
- Name
- name
- Type
- string
- Description
タスク作成時に指定されたタスク名です。名前が指定されていない場合は空文字列になります。
- Name
- status
- Type
- string
- Description
タスクのステータスです。取り得る値は
PENDING、IN_PROGRESS、SUCCEEDED、FAILED、CANCELEDのいずれかです。
- Name
- progress
- Type
- integer
- Description
タスクの progress です。タスクがまだ開始されていない場合、このプロパティは
0になります。タスクが成功すると100になります。
- Name
- created_at
- Type
- timestamp
- Description
タスクが作成された時刻のタイムスタンプ(ミリ秒単位)です。
タイムスタンプは、RFC 3339
標準に従い、1970年1月1日 UTC から経過したミリ秒数を表します。 例えば、2023年9月1日金曜日 12:00:00 PM GMT は1693569600000と表されます。これは Meshy API のすべてのタイムスタンプに当てはまります。
- Name
- started_at
- Type
- timestamp
- Description
タスクが開始された時刻のタイムスタンプ(ミリ秒単位)です。タスクがまだ開始されていない場合、このプロパティは
0になります。
- Name
- finished_at
- Type
- timestamp
- Description
タスクが終了した時刻のタイムスタンプ(ミリ秒単位)です。タスクがまだ終了していない場合、このプロパティは
0になります。
- Name
- expires_at
- Type
- timestamp
- Description
タスク結果が失効する時刻のタイムスタンプ(ミリ秒単位)です。
- Name
- preceding_tasks
- Type
- integer
- Description
先行するタスクの数です。
このフィールドの値は、タスクのステータスが
PENDINGの場合にのみ意味を持ちます。
- Name
- task_error
- Type
- object
- Description
失敗したタスクのエラー詳細です。
task_errorオブジェクトの全リファレンスについてはエラーを参照してください。
- Name
- consumed_credits
- Type
- integer
- Description
このタスクによって消費された consumed_credits の数です。タスクのステータスが
PENDING、IN_PROGRESS、またはSUCCEEDEDの場合に存在します。FAILEDタスクの場合は0を返します(失敗時にはクレジットが返還されます)。
- Name
- image_urls
- Type
- array of strings
- Description
このプロトタイプタスクによって生成されたコンセプト画像候補のダウンロード可能な URL です。現在、API は常にちょうど1つの候補を返しますが、将来のリビジョンで破壊的変更なしに複数の候補を返せるよう、このフィールドは配列になっています。
Example Figure Prototype Task Object
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "creative-lab-figure-prototype",
"name": "",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1729123456000,
"started_at": 1729123460000,
"finished_at": 1729123486000,
"expires_at": 1729382686000,
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 6,
"image_urls": [
"https://assets.meshy.ai/***/concept.png?Expires=***"
]
}
フィギュアビルドタスクオブジェクト
フィギュアビルドタスクオブジェクトは、成功したプロトタイプタスクからテクスチャ付きの3Dフィギュアを生成するために Meshy が管理する作業単位です。これは画像から3Dが使用するものと同じ image-to-3D パイプラインを実行するため、出力フィールドはそのエンドポイントのタスクオブジェクトと同じ構成になっています。
プロパティ
- Name
- id
- Type
- string
- Description
タスクの一意な識別子。
- Name
- type
- Type
- string
- Description
タスクの種類。値は
creative-lab-figure-buildです。
- Name
- name
- Type
- string
- Description
タスク作成時に指定されたタスク名。名前が指定されなかった場合は空文字列になります。
- Name
- status
- Type
- string
- Description
タスクのステータス。取り得る値は
PENDING、IN_PROGRESS、SUCCEEDED、FAILED、CANCELEDのいずれかです。
- Name
- progress
- Type
- integer
- Description
タスクの進行状況。タスクがまだ開始されていない場合、このプロパティは
0になります。タスクが成功すると100になります。
- Name
- created_at
- Type
- timestamp
- Description
タスクが作成された時刻のタイムスタンプ(ミリ秒単位)。
- Name
- started_at
- Type
- timestamp
- Description
タスクが開始された時刻のタイムスタンプ(ミリ秒単位)。
- Name
- finished_at
- Type
- timestamp
- Description
タスクが終了した時刻のタイムスタンプ(ミリ秒単位)。
- Name
- expires_at
- Type
- timestamp
- Description
タスク結果の有効期限のタイムスタンプ(ミリ秒単位)。
- Name
- preceding_tasks
- Type
- integer
- Description
先行するタスクの数。ステータスが
PENDINGの場合にのみ意味を持ちます。
- Name
- task_error
- Type
- object
- Description
失敗したタスクのエラー詳細。
task_errorオブジェクトの完全なリファレンスについてはエラーを参照してください。
- Name
- consumed_credits
- Type
- integer
- Description
このタスクで消費されたクレジット数。
FAILEDタスクの場合は0を返します(失敗時にはクレジットが返還されます)。
- Name
- prompt
- Type
- string
- Description
フィギュアビルドでは常に空です。画像から3Dで使用される共通の
V2ImageTo3DTaskResponse形式とのエンドポイント間の互換性のために存在します。
- Name
- negative_prompt
- Type
- string
- Description
フィギュアビルドでは常に空です。エンドポイント間の互換性のために存在します。
- Name
- texture_prompt
- Type
- string
- Description
フィギュアビルドでは常に空です。エンドポイント間の互換性のために存在します。
- Name
- texture_image_url
- Type
- string
- Description
フィギュアビルドでは常に空です。エンドポイント間の互換性のために存在します。
- Name
- model_urls
- Type
- object
- Description
生成された3Dモデルのダウンロード可能なURL。フィギュアビルドは、テクスチャ付きの GLB に加えて、Wavefront OBJ を好むパイプライン向けに OBJ + MTL のペアを出力します。このフィールドの形式は画像から3Dの model_urlsオブジェクトと一致しているため、将来的にフォーマットが追加されても破壊的変更なしに組み込むことができます。
- Name
glb- Type
- string
- Description
テクスチャ付き GLB ファイルのダウンロード可能なURL。
- Name
obj- Type
- string
- Description
Wavefront OBJ ファイル(ジオメトリ + UV)のダウンロード可能なURL。
- Name
mtl- Type
- string
- Description
OBJ に付随する MTL マテリアルファイルのダウンロード可能なURL。
objおよびtexture_urls[0].base_colorのエントリとセットで使用してください。
- Name
- thumbnail_url
- Type
- string
- Description
モデルファイルのサムネイル画像のダウンロード可能なURL。
- Name
- texture_urls
- Type
- array
- Description
このタスクで生成されたテクスチャURLオブジェクトの配列。現在はベースカラーマップを含む単一のオブジェクトのみが含まれます。
- Name
base_color- Type
- string
- Description
ベースカラーマップ画像のダウンロード可能なURL。
Example Figure Build Task Object
{
"id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
"type": "creative-lab-figure-build",
"name": "",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1729123500000,
"started_at": 1729123510000,
"finished_at": 1729123535000,
"expires_at": 1729382735000,
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 20,
"prompt": "",
"negative_prompt": "",
"texture_prompt": "",
"texture_image_url": "",
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***",
"obj": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.obj?Expires=***",
"mtl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.mtl?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/preview.png?Expires=***",
"texture_urls": [
{
"base_color": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/texture_0.png?Expires=***"
}
]
}