Creative Lab — ブロックフィギュア API
ソース写真をブロックスタイルのコレクタブルな3Dミニフィギュアに変換する2段階プロセスです:
プロトタイプは入力写真からスタイル化されたコンセプト画像を生成し、
ビルドはそのコンセプト画像をテクスチャ付きの3Dモデルに変換します。これらの2つの段階はinput_task_idを介してリンクされています。
POST /openapi/creative-lab/brick-figure/v1/prototypePOST /openapi/creative-lab/brick-figure/v1/build
ブリックフィギュアプロトタイプタスクを作成する
ソース写真から単一のブリックスタイルのコンセプト画像を生成します。
返されたタスクIDは、input_task_id としてビルドエンドポイントに渡します。
応答の形式については、
The Brick Figure Prototype Task Object
を参照してください。
パラメータ
- Name
- image_url
- Type
- string
- 必須
- Description
Meshy がブリックミニフィギュアとしてスタイライズするためのソース写真です。現在サポートしている形式は
.jpg、.jpeg、.png、および.webpです。画像を提供するには以下の2つの方法があります:
- 公開アクセス可能なURL: 公開インターネットからアクセス可能なURL。
- Data URI: 画像のbase64エンコードされたデータURI。Data URIの例:
data:image/jpeg;base64,<your base64-encoded image data>。
- Name
- name
- Type
- string
- Description
表示目的のためのオプションのタスク名。最大100文字。
返却値
応答の result プロパティには、新しく作成されたブリックフィギュアプロトタイプタスクのタスク id が含まれています。Get a Task エンドポイントをポーリングするか、タスクが SUCCEEDED に達するまで stream にサブスクライブし、そのIDをinput_task_id として build endpoint に渡します。
失敗モード
- Name
400 - Bad Request- Description
リクエストは受け付けられませんでした。一般的な理由:
- パラメータの欠如:
image_urlが必要です。 - 無効な画像形式: 提供された
image_urlがサポートされていない形式です(.jpg、.jpeg、.png、.webp)。 - 画像の寸法が範囲外: 画像が小さすぎる、最大ファイルサイズを超えている、または最大ピクセル数を超えています。
- アクセスできないURL:
image_urlがダウンロードできませんでした(404またはtimeout)。 - 無効なData URI: base64文字列が不正です。
- コンテンツがフラグされました: NSFWまたは知的財産のモデレーションにより入力画像がフラグされました。
- パラメータの欠如:
- Name
401 - Unauthorized- Description
認証に失敗しました。APIキーを確認してください。
- Name
402 - Payment Required- Description
このタスクを実行するのにクレジットが不足しています。
- Name
403 - Forbidden- Description
入力画像が知的財産権の侵害としてフラグ付けされました。
- Name
429 - Too Many Requests- Description
レート制限を超えました。
Request
# ステージ1: ブリックスタイルのコンセプト画像を生成する
curl https://api.meshy.ai/openapi/creative-lab/brick-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"
}
Brick Figure ビルドタスクを作成する
SUCCEEDED 状態のプロトタイプタスクから最終的なテクスチャ付き 3D ブリックフィギュアを生成します。このビルドはImage to 3Dと同じ画像から3Dパイプラインを実行するため、レスポンスオブジェクトの形式と出力URLのリストは完全に一致します。レスポンスの形式については、Brick Figure ビルドタスクオブジェクトを参照してください。
パラメータ
- Name
- input_task_id
- Type
- string
- 必須
- Description
この同じ OpenAPI エンドポイントを介して作成されたプロトタイプタスクのタスクIDです。プロトタイプは同じ APIキーで作成され、
SUCCEEDEDに到達し、候補画像を1つ正しく生成している必要があります。ウェブアプリを通じて作成されたプロトタイプタスクは受け入れられません。ビルドエンドポイントは、
POST /openapi/creative-lab/brick-figure/v1/prototypeによって作成されたプロトタイプタスクのみを受け入れ、それ以外のソースは404エラーとします。
- Name
- name
- Type
- string
- Description
表示用のオプションタスク名です。最大100文字まで。
戻り値
レスポンスの result プロパティには、新たに作成されたブリックフィギュアビルドタスクのタスク id が含まれています。タスクを取得エンドポイントでポーリングするか、タスクが SUCCEEDED に到達するまでストリームを購読し、その後、あなたの下流パイプラインが OBJ を好む場合は model_urls.glb からテクスチャ付き GLB をダウンロードするか、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
参照されたプロトタイプタスクは存在しないか、異なるユーザーに属しているか、ウェブアプリを通じて作成されました(APIモードのプロトタイプタスクのみがビルドに連鎖します)。
- Name
429 - Too Many Requests- Description
レート制限を超過しました。
Request
# ステージ2: 成功したプロトタイプタスクからのビルドを連鎖する
curl https://api.meshy.ai/openapi/creative-lab/brick-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を受け取り、プロトタイプまたはビルドタスクを取得します。URLパスはタスクのステージと一致している必要があります。/prototype/:idを通じて取得されたビルドタスクは404を返し、その逆も同様です。
レスポンスの形状については、The Brick Figure Prototype Task ObjectとThe Brick Figure Build Task Objectを参照してください。
パラメータ
- Name
- id
- Type
- path
- Description
取得するブリックフィギュアタスクの一意の識別子。
戻り値
レスポンスにはブリックフィギュアタスクオブジェクトが含まれます。要求されたステージによって形状が異なります。
Request
# プロトタイプ
curl https://api.meshy.ai/openapi/creative-lab/brick-figure/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
# ビルド
curl https://api.meshy.ai/openapi/creative-lab/brick-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-brick-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-brick-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": 30,
"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/brick-figure/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
// 成功時には204 No Contentを返します(空の本体)。
ブリックフィギュアタスクのストリーム
Server-Sent Events (SSE) を介してブリックフィギュアタスクのリアルタイム更新をストリームします。
URL パスはタスクのステージに一致しなければならず、
/prototype/:buildId/stream でストリームを開くと、単一の event: error ペイロードが status_code: 404 で送信され、ストリームが閉じられます。
パラメータ
- Name
- id
- Type
- path
- Description
ストリームするブリックフィギュアタスクの一意の識別子。
戻り値
ブリックフィギュアプロトタイプ または
ブリックフィギュアビルド タスクオブジェクトのストリームは
Server-Sent Events として返されます。PENDING または IN_PROGRESS タスクの場合、応答ストリームには必要な progress および status フィールドのみが含まれます。
リクエスト
curl -N https://api.meshy.ai/openapi/creative-lab/brick-figure/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"
レスポンスストリーム
// エラーイベントの例(間違ったステージまたはタスクが見つからない)
event: error
data: {
"status_code": 404,
"message": "Task not found"
}
// メッセージイベントの例はタスクの進行状況を示します。
// `PENDING` または `IN_PROGRESS` タスクの場合、レスポンスストリームには全フィールドが含まれません。
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-brick-figure-build",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1729123500000,
"started_at": 1729123510000,
"finished_at": 1729123535000,
"expires_at": 1729382735000,
"task_error": null,
"consumed_credits": 30,
"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=***"
}
]
}
ブリックフィギュアタスクの一覧
単一のステージに対するブリックフィギュアタスクのページネーションされた一覧を取得します。URLパスはステージを選択します — /prototypeはプロトタイプタスクを返し、/buildはビルドタスクを返します。別のステージからのタスクはどちらのレスポンスにも含まれません。
パスパラメータ
- Name
- stage
- Type
- path
- 必須
- Description
prototypeまたはbuildのいずれか。コレクションは、URLに一致したステージのタスクのみを返します —/prototypeを取得する場合、ビルドタスクは返されません、その逆も真です。
クエリパラメータ
- 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: 作成時間で降順にソート。
返り値
返り値はステージごとのタスクオブジェクトのページネーションされた一覧です — /prototypeをリストする場合はブリックフィギュアプロトタイプタスクオブジェクト、/buildをリストする場合はブリックフィギュアビルドタスクオブジェクトです。
Request
# プロトタイプタスクの一覧
curl https://api.meshy.ai/openapi/creative-lab/brick-figure/v1/prototype?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
# ビルドタスクの一覧
curl https://api.meshy.ai/openapi/creative-lab/brick-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-brick-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=***"
]
}
]
レンガフィギュアプロトタイプタスクオブジェクト
レンガフィギュアプロトタイプタスクオブジェクトは、ソース写真からレンガスタイルのコンセプト画像を生成するためにMeshyが追跡する作業単位です。この段階の出力は、input_task_idを介して構築段階に連結されます。
プロパティ
- Name
- id
- Type
- string
- Description
タスクの一意識別子です。実装の詳細としてkソート可能なUUIDをタスクIDに使用しますが、IDの形式に関する仮定はしないでください。
- Name
- type
- Type
- string
- Description
タスクの種類です。値は
creative-lab-brick-figure-prototypeです。
- 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
タスクが作成された時点のタイムスタンプです(ミリ秒単位)。
タイムスタンプは、1970年1月1日UTCから経過したミリ秒数を表し、RFC 3339
標準に従います。例えば、2023年9月1日金曜日12:00:00 PM GMTは、1693569600000として表されます。これはMeshy APIのすべてのタイムスタンプに適用されます。
- Name
- started_at
- Type
- timestamp
- Description
タスクが開始された時点のタイムスタンプです(ミリ秒単位)。タスクがまだ開始されていない場合、このプロパティは
nullになります。
- Name
- finished_at
- Type
- timestamp
- Description
タスクが終了した時点のタイムスタンプです(ミリ秒単位)。タスクがまだ終了していない場合、このプロパティは
nullになります。
- 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
このタスクで消費されたクレジットの数です。タスクのステータスが
PENDING,IN_PROGRESS, またはSUCCEEDEDの場合に表示されます。FAILEDタスクの場合は0を返し(失敗時にはクレジットが返金されます)。
- Name
- image_urls
- Type
- array of strings
- Description
このプロトタイプタスクで生成されたコンセプト画像候補のダウンロード可能なURLです。現在、APIは常に正確に1つの候補を返しますが、このフィールドは将来のリビジョンで複数の候補を非破壊的に表示できるようにするための配列です。
Example Brick Figure Prototype Task Object
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "creative-lab-brick-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 Brick Figure Build Task Object
Brick Figure Build Taskオブジェクトは、成功したプロトタイプタスクからテクスチャ付き3Dブリックフィギュアを生成するためにMeshyが追跡する作業単位です。このオブジェクトは、画像から3Dで使用されるのと同じ画像から3Dへのパイプラインを実行するので、出力フィールドはそのエンドポイントのタスクオブジェクトを反映しています。
プロパティ
- Name
- id
- Type
- string
- Description
タスクの一意識別子。
- Name
- type
- Type
- string
- Description
タスクの種類。値は
creative-lab-brick-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。
例 - ブロックフィギュアビルドタスクオブジェクト
{
"id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
"type": "creative-lab-brick-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": 30,
"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=***"
}
]
}