Creative Lab — キーチェーン API
ソース写真を、3Dプリント可能なキーチェーンメダリオン（バッジ形状の
カラー化された深度レリーフ）へ、2段階で変換します。prototype は入力写真からカラー化された
コンセプト画像を生成し、その後 build がそのコンセプト画像を
レリーフ 3D モデルに変換します。2つの段階は input_task_id を介して関連付けられます。
POST /openapi/creative-lab/keychain/v1/prototypePOST /openapi/creative-lab/keychain/v1/build
キーチェーンのプロトタイプタスクを作成
ソース写真から、カラー化された単一のコンセプト画像を生成します。
返されたタスク ID は、build
endpoint に input_task_id として渡します。レスポンスの形式については
キーチェーンプロトタイプタスクオブジェクト
を参照してください。
パラメータ
- Name
- image_url
- Type
- string
- 必須
- Description
Meshy がキーチェーン用のコンセプト画像としてカラー化するためのソース写真です。現在、
.jpg、.jpeg、.png、.webp形式をサポートしています。画像を提供する方法は 2 つあります。
- 公開アクセス可能な URL: 公開インターネットからアクセス可能な URL。
- Data URI: 画像の base64 エンコードされたデータ URI。データ URI の例:
data:image/jpeg;base64,<your base64-encoded image data>。
- Name
- name
- Type
- string
- Description
表示用の任意のタスク名。最大 100 文字です。
戻り値
レスポンスの result プロパティには、新しく作成されたキーチェーンプロトタイプタスクのタスク id が含まれます。タスクが SUCCEEDED に到達するまで タスクを取得 endpoint をポーリングするか、stream を購読し、その ID を build 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
# Stage 1: generate a colorized keychain concept image
curl https://api.meshy.ai/openapi/creative-lab/keychain/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プリント可能なキーチェーンメダリオンを生成します。ビルドは、プロトタイプのカラー化されたコンセプト画像に対して深度マップのレリーフパイプラインを実行し、指定した形式で単一のメッシュアーティファクトを提供します。レスポンス形式については、 キーチェーンビルドタスクオブジェクト を参照してください。
パラメータ
- Name
- input_task_id
- Type
- string
- 必須
- Description
この同じOpenAPI endpointを介して作成されたプロトタイプタスクのタスクIDです。プロトタイプは同じAPI keyで作成されている必要があり、
SUCCEEDEDに到達していて、かつ候補画像を正確に1つ生成している必要があります。Webアプリから作成されたプロトタイプタスクは受け付けられません — ビルドendpointは
POST /openapi/creative-lab/keychain/v1/prototypeによって生成されたプロトタイプタスクのみを受け付け、それ以外のソースは404で拒否します。
- Name
- name
- Type
- string
- Description
表示用の任意のタスク名です。最大100文字です。
options
レリーフジオメトリ用の任意の調整パラメータです。すべてのフィールドには適切なデフォルト値があります — 上書きしたいものだけを送信してください。
- Name
- badge_shape
- Type
- string
- デフォルト circle
- Description
キーチェーンメダリオンの外形シルエットです。利用可能な値:
circle（デフォルト）rounded-recthexagonshieldstar
- Name
- size_mm
- Type
- number
- デフォルト 40
- Description
キーチェーンの外接正方形の辺の長さ（ミリメートル）です。範囲:
(0, 400]。
- Name
- relief_height_mm
- Type
- number
- デフォルト 2.2
- Description
ベース上の最大レリーフ高さ（ミリメートル）です。範囲:
[0, 20]。
- Name
- relief_offset_mm
- Type
- number
- デフォルト 0
- Description
押し出し前にレリーフへ適用される垂直オフセット（ミリメートル）です。範囲:
[0, 20]。
- Name
- base_thickness_mm
- Type
- number
- デフォルト 0.1
- Description
レリーフの背面にある平坦なベースプレートの厚さ（ミリメートル）です。範囲:
[0, 20]。
- Name
- has_closed_back
- Type
- boolean
- デフォルト true
- Description
メダリオンの背面を閉じたサーフェスとして封止するかどうかです。開いたシェルにするには
falseに設定します。
- Name
- relief_curve
- Type
- string
- デフォルト linear
- Description
深度マップ値をレリーフ高さへマッピングする転送曲線です。利用可能な値:
linear（デフォルト）gammas-curve
- Name
- curve_param
- Type
- number
- デフォルト 1.0
- Description
転送曲線の形状パラメータです（
relief_curveがgammaの場合にのみ意味があります）。範囲:(0, 10]。
- Name
- invert_depth
- Type
- boolean
- デフォルト false
- Description
深度マップの解釈を反転し、暗い領域がより高いレリーフになるようにします。
- Name
- smoothing
- Type
- number
- デフォルト 0.24
- Description
レリーフ抽出前に深度マップへ適用されるスムージング強度です。範囲:
[0, 10]。
- Name
- relief_scale
- Type
- number
- デフォルト 1.0
- Description
relief_height_mmの上に適用される垂直スケール倍率です。範囲:(0, 10]。
- Name
- depth_threshold
- Type
- number
- デフォルト 0.1
- Description
深度マップ値のローパスしきい値です。これを下回る値はすべてゼロにクランプされます。範囲:
[0, 1]。
- Name
- remove_background
- Type
- boolean
- デフォルト true
- Description
レリーフ化の前に、プロトタイプのコンセプト画像の背景を自動的に削除します。
- Name
- export_resolution
- Type
- integer
- デフォルト 512
- Description
エクスポートに使用されるメッシュ解像度です。範囲:
[64, 2048]。
output
任意のワイヤーフォーマットセレクタです。デフォルトは glb です。
- Name
- format
- Type
- string
- デフォルト glb
- Description
ビルドによって返されるアーティファクトバンドルです。利用可能な値:
glb（デフォルト）—model_urls.glbの下に単一のmodel.glbを返します。obj—model.obj+model.mtl+texture.pngをzip化し、model_urls.objの下にバンドルを返します。zip— ジェネレーターが出力するすべてのアーティファクトをzip化し、model_urls.bundle_zipの下にバンドルを返します。
戻り値
レスポンスの result プロパティには、新しく作成されたキーチェーンビルドタスクのタスク id が含まれます。タスクが SUCCEEDED に到達するまで タスクを取得 endpointをポーリングするか、stream を購読し、その後 model_urls 内の単一のエントリからアーティファクトをダウンロードしてください。
失敗モード
- Name
400 - Bad Request- Description
リクエストは受け入れられませんでした。一般的な原因:
- パラメータ不足:
input_task_idは必須です。 - 無効なUUID:
input_task_idが有効なUUIDではありません。 - 親が成功していない: 参照されたプロトタイプタスクがまだ
SUCCEEDEDに到達していません。 - 候補なし: プロトタイプタスクは成功しましたが、候補画像を生成しませんでした。
- オプションが範囲外:
optionsフィールドのいずれかが許可された範囲または列挙セットの外にあります。
- パラメータ不足:
- 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
# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/build \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"options": {
"badge_shape": "circle",
"size_mm": 40,
"relief_height_mm": 2.5
},
"output": {
"format": "glb"
}
}'
Response
{
"result": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb"
}
Keychain タスクを取得する
有効なタスク id を指定して、prototype または build タスクを取得します。URL パスは
タスクのステージと一致している必要があります — build タスクを
/prototype/:id から取得すると 404 が返され、その逆も同様です。
レスポンスの形状については、Keychain Prototype タスクオブジェクト および Keychain Build タスクオブジェクト を 参照してください。
パラメーター
- Name
- id
- Type
- path
- Description
取得する keychain タスクの一意の識別子。
戻り値
レスポンスには keychain タスクオブジェクトが含まれます。形状はリクエストされた ステージによって異なります。
Request
# Prototype
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
# Build
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Prototype Response
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "creative-lab-keychain-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-keychain-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,
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?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/keychain/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
// Returns 204 No Content on success (empty body).
Keychainタスクをストリーミングする
Server-Sent Events (SSE) 経由で、Keychainタスクのリアルタイム更新をストリーミングします。
URLパスはタスクのステージと一致している必要があります —
/prototype/:buildId/stream でストリームを開くと、status_code: 404 を含む単一の event: error ペイロードが送信され、ストリームが閉じられます。
パラメーター
- Name
- id
- Type
- path
- Description
ストリーミングするKeychainタスクの一意の識別子。
戻り値
Keychain Prototype
または Keychain Build タスクオブジェクトのストリームを
Server-Sent Eventsとして返します。PENDING または IN_PROGRESS タスクの場合、レスポンス
ストリームには必要な progress および status フィールドのみが含まれます。
Request
curl -N https://api.meshy.ai/openapi/creative-lab/keychain/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-keychain-build",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1729123500000,
"started_at": 1729123510000,
"finished_at": 1729123535000,
"expires_at": 1729382735000,
"task_error": null,
"consumed_credits": 20,
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?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
ページサイズの上限。許可される最大値は
50件です。
- Name
- sort_by
- Type
- string
- デフォルト -created_at
- Description
ソート対象のフィールド。利用可能な値:
+created_at: 作成時刻の昇順でソートします。-created_at: 作成時刻の降順でソートします。
戻り値
ステージごとのタスクオブジェクトのページ分割された一覧を返します —
/prototype を一覧取得する場合は
キーチェーンプロトタイプタスクオブジェクト、
/build を一覧取得する場合は
キーチェーンビルドタスクオブジェクト です。
Request
# List prototype tasks
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/prototype?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
# List build tasks
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/build?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response (List Prototype Tasks)
[
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "creative-lab-keychain-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-keychain-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オブジェクトのリファレンスについては、Errors を参照してください。
- Name
- consumed_credits
- Type
- integer
- Description
このタスクによって消費されたクレジットの数です。タスクのステータスが
PENDING、IN_PROGRESS、またはSUCCEEDEDの場合に存在します。FAILEDタスクの場合は0を返します（失敗時にはクレジットが返還されます）。
- Name
- image_urls
- Type
- array of strings
- Description
このプロトタイプタスクによって生成されたコンセプト画像候補のダウンロード可能な URL です。現在、API は常に候補を 1 つだけ返します。このフィールドは配列であるため、将来の改訂で破壊的変更なしに複数の候補を提供できます。
Example Keychain Prototype Task Object
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "creative-lab-keychain-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が追跡する作業単位です。 ビルドはプロトタイプのコンセプト画像に対して深度マップレリーフパイプラインを実行し、 呼び出し元が要求した形式で単一のメッシュアーティファクトを公開します。
プロパティ
- Name
- id
- Type
- string
- Description
タスクの一意の識別子。
- Name
- type
- Type
- string
- Description
タスクの種類。値は
creative-lab-keychain-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
- model_urls
- Type
- object
- Description
生成されたアーティファクトのダウンロード可能な URL。アーティファクト名をキーとします。常に正確に 1 つのエントリを含みます — ビルドリクエストの
output.formatで要求された形式です。キーは要求された形式と一致します。- Name
glb- Type
- string
- Description
GLB ファイルへのダウンロード可能な URL。
output.formatがglb（デフォルト）の場合に存在します。
- Name
obj- Type
- string
- Description
model.obj、model.mtl、texture.pngを含む zip バンドルへのダウンロード可能な URL。output.formatがobjの場合に存在します。
- Name
bundle_zip- Type
- string
- Description
ジェネレーターが出力するすべてのアーティファクトの zip バンドルへのダウンロード可能な URL。
output.formatがzipの場合に存在します。
Example Keychain Build Task Object
{
"id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
"type": "creative-lab-keychain-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,
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
}
}