Creative Lab — Figure API

ソース写真を、ちびキャラ風のコレクション用3Dフィギュアに2段階で変換します: prototype は入力写真からスタイル化されたコンセプト画像を生成し、その後 build がそのコンセプト画像をテクスチャ付き3Dモデルに変換します。この2つの段階は input_task_id によって関連付けられます。

POST /openapi/creative-lab/figure/v1/prototype
POST /openapi/creative-lab/figure/v1/build

POST/openapi/creative-lab/figure/v1/prototype

フィギュアプロトタイプタスクを作成

ソース写真から、ちびスタイルのコンセプト画像を1枚生成します。返されるタスクIDは、ビルド endpoint に 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文字です。

戻り値

レスポンスの result プロパティには、新しく作成されたフィギュアプロトタイプタスクのタスク id が含まれます。タスクが SUCCEEDED に達するまでタスクを取得 endpoint をポーリングするか、stream を購読し、そのIDをビルド endpoint に input_task_id として渡します。

失敗モード

Name
400 - Bad Request
Description
リクエストは受け付けられませんでした。一般的な原因:
- パラメータ不足: image_url は必須です。
- 無効な画像形式: 指定された image_url はサポートされている形式 (.jpg、.jpeg、.png、.webp) ではありません。
- 画像サイズが範囲外: 画像が小さすぎる、最大ファイルサイズを超えている、または最大ピクセル数を超えています。
- 到達不能なURL: image_url をダウンロードできませんでした（404またはタイムアウト）。
- 無効なData URI: base64文字列の形式が正しくありません。
- コンテンツがフラグ付け済み: 入力画像がNSFWまたは知的財産のモデレーションによってフラグ付けされました。
Name
401 - Unauthorized
Description
認証に失敗しました。API keyを確認してください。
Name
402 - Payment Required
Description
このタスクを実行するためのクレジットが不足しています。
Name
429 - Too Many Requests
Description
レート制限を超えています。

Request

POST

/openapi/creative-lab/figure/v1/prototype

# 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"
}

Prototype example

Start with a source portrait, then generate the prototype image used by the build stage.

Creative Lab Figureの入力として使用されるソースポートレート — Prototype input

ソース写真から生成されたちびスタイルのフィギュアプロトタイプ画像 — Prototype output

POST/openapi/creative-lab/figure/v1/build

Figure ビルドタスクの作成

成功したプロトタイプタスクから、最終的なテクスチャ付き 3D Figure を生成します。このビルドは Image to 3D と同じ画像から 3D へのパイプラインを実行するため、レスポンスオブジェクトの形式と出力 URL の一覧は完全に一致します。レスポンスの形状については Figure ビルドタスクオブジェクトを参照してください。

パラメータ

Name
input_task_id
Type
string
必須
Description
この同じ OpenAPI endpoint 経由で作成されたプロトタイプタスクのタスク ID です。プロトタイプは同じ API key で作成されている必要があり、SUCCEEDED に到達していて、かつ候補画像をちょうど 1 つ生成している必要があります。
Web アプリから作成されたプロトタイプタスクは受け付けられません — ビルド endpoint は POST /openapi/creative-lab/figure/v1/prototype によって生成されたプロトタイプタスクのみを受け付け、それ以外のソースは 404 で拒否します。
Name
name
Type
string
Description
表示用の任意のタスク名です。最大 100 文字です。

戻り値

レスポンスの result プロパティには、新しく作成された Figure ビルドタスクのタスク id が含まれます。タスクが SUCCEEDED に到達するまで Get a Task endpoint をポーリングするか、stream を購読してください。その後、テクスチャ付き GLB を model_urls.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 key を確認してください。
Name
402 - Payment Required
Description
このタスクを実行するためのクレジットが不足しています。
Name
404 - Not Found
Description
参照されたプロトタイプタスクが存在しない、別のユーザーに属している、または Web アプリから作成されています（API モードのプロトタイプタスクのみがビルドに連鎖できます）。
Name
429 - Too Many Requests
Description
レート制限を超過しています。

Request

POST

/openapi/creative-lab/figure/v1/build

# 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"
}

Build example

The build task turns the selected prototype image into a downloadable textured 3D model.

Creative Lab Figure build model preview — Build model preview

GET/openapi/creative-lab/figure/v1/(prototype|build)/:id

フィギュアタスクを取得

有効なタスク id を指定して、プロトタイプまたはビルドタスクを取得します。URL パスはタスクのステージと一致している必要があります — ビルドタスクを /prototype/:id 経由で取得すると 404 が返され、その逆も同様です。

レスポンス形式については、The Figure Prototype Task Object および The Figure Build Task Object を参照してください。

パラメータ

Name
id
Type
path
Description
取得するフィギュアタスクの一意の識別子。

戻り値

レスポンスにはフィギュアタスクオブジェクトが含まれます。形式はリクエストされたステージによって異なります。

Request

GET

/openapi/creative-lab/figure/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578

# 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=***"
    }
  ]
}

DELETE/openapi/creative-lab/figure/v1/(prototype|build)/:id

Figureタスクを削除する

Figureタスクをキャンセルします。タスクがまだPENDINGの場合、作成時に消費されたクレジットは返還されます。すでに IN_PROGRESSのタスクは返還なしでキャンセルされます（ワーカーがすでにリソースを消費している可能性があります）。すでに終端状態（SUCCEEDED、FAILED、CANCELED）に達しているタスクはキャンセルできません。

URLパスはタスクのステージと一致している必要があります — /prototype/:buildIdに対するDELETEは 404を返します。

パスパラメータ

Name
id
Type
path
Description
キャンセルするFigureタスクの一意の識別子。

戻り値

成功時は空の本文で204 No Contentを返します。

失敗モード

Name
400 - Bad Request
Description
タスクはすでに終端状態にあり、キャンセルできません。
Name
404 - Not Found
Description
タスクが存在しない、別のユーザーに属している、またはそのステージがURLパスと一致しません。

Request

DELETE

/openapi/creative-lab/figure/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578

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).

GET/openapi/creative-lab/figure/v1/(prototype|build)/:id/stream

フィギュアタスクをストリーミング

Server-Sent Events（SSE）を介して、フィギュアタスクのリアルタイム更新をストリーミングします。 URL パスはタスクのステージと一致している必要があります — /prototype/:buildId/stream でストリームを開くと、status_code: 404 を含む単一の event: error ペイロードが送信され、ストリームが閉じられます。

パラメータ

Name
id
Type
path
Description
ストリーミングするフィギュアタスクの一意の識別子。

戻り値

Server-Sent Events として、フィギュアプロトタイプまたはフィギュアビルドタスクオブジェクトのストリームを返します。 PENDING または IN_PROGRESS タスクの場合、レスポンスストリームには必要な progress および status フィールドのみが含まれます。

Request

GET

/openapi/creative-lab/figure/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream

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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
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=***"
    }
  ]
}

GET/openapi/creative-lab/figure/v1/(prototype|build)

フィギュアタスク一覧の取得

単一ステージのフィギュアタスクのページ分割された一覧を取得します。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
ページサイズの上限。許可される最大値は 50 件です。
Name
sort_by
Type
string
デフォルト -created_at
Description
ソート対象のフィールド。使用可能な値:
- +created_at: 作成時刻の昇順でソートします。
- -created_at: 作成時刻の降順でソートします。

戻り値

ステージごとのタスクオブジェクトのページ分割された一覧を返します — /prototype を一覧表示する場合はフィギュアプロトタイプタスクオブジェクト、 /build を一覧表示する場合はフィギュアビルドタスクオブジェクトです。

Request

GET

/openapi/creative-lab/figure/v1/prototype

# 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=***"
    ]
  }
]

フィギュアプロトタイプタスクオブジェクト

フィギュアプロトタイプタスクオブジェクトは、ソース写真からちびスタイルのコンセプト画像を生成するために 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
タスクの進捗です。タスクがまだ開始されていない場合、このプロパティは 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
タスクが開始された時刻のタイムスタンプ（ミリ秒）です。タスクがまだ開始されていない場合、このプロパティは 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
このタスクによって消費されたクレジット数です。タスクのステータスが 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 が追跡する作業単位です。これは Image to 3D で使用されるものと同じ画像から 3D へのパイプラインを実行するため、出力フィールドはその endpoint のタスクオブジェクトと対応しています。

プロパティ

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
figure build では常に空です。Image to 3D で使用される共有の V2ImageTo3DTaskResponse 形状とのクロスエンドポイント互換性のために存在します。
Name
negative_prompt
Type
string
Description
figure build では常に空です。クロスエンドポイント互換性のために存在します。
Name
texture_prompt
Type
string
Description
figure build では常に空です。クロスエンドポイント互換性のために存在します。
Name
texture_image_url
Type
string
Description
figure build では常に空です。クロスエンドポイント互換性のために存在します。
Name
model_urls
Type
object
Description
生成された 3D モデルのダウンロード可能な URL。figure build は、テクスチャ付き GLB に加えて、Wavefront OBJ を優先するパイプライン向けに OBJ + MTL のペアを出力します。フィールドの形状は Image to 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=***"
    }
  ]
}