Creative Lab — キーホルダー API
ソース写真を3Dプリント可能なキーホルダーメダリオンに変換します — バッジ型の着色された深度レリーフ — 2つの段階で行います: プロトタイプ は入力写真から着色されたコンセプト画像を生成し、その後 ビルド がそのコンセプト画像をレリーフ3Dモデルに変換します。この2つの段階は input_task_id を介してリンクされています。
POST /openapi/creative-lab/keychain/v1/prototypePOST /openapi/creative-lab/keychain/v1/build
キーホルダープロトタイプタスクの作成
ソース写真から単一のカラー化されたコンセプト画像を生成します。返されるタスクIDは、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として返され、任意の背景に被写体を合成できます。これは、このエンドポイントが返す画像にのみ影響します。同名のビルドオプション（デフォルトは
true）とは別で、レリーフ化前の背景削除を制御します。
戻り値
レスポンスのresultプロパティには、新しく作成されたキーホルダープロトタイプタスクのタスクidが含まれています。タスクの取得エンドポイントをポーリングするか、タスクがSUCCEEDEDに達するまでストリームを購読し、そのIDをビルドエンドポイントに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または知的財産のモデレーションによってフラグが立てられました。
- パラメータの欠如:
- Name
401 - Unauthorized- Description
認証に失敗しました。APIキーを確認してください。
- 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エンドポイントを介して作成されたプロトタイプタスクのタスクID。プロトタイプは同じAPIキーで作成され、
SUCCEEDEDに達し、正確に1つの候補画像を生成している必要があります。Webアプリを通じて作成されたプロトタイプタスクは受け入れられません — 構築エンドポイントは
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
レリーフ化する前にプロトタイプのコンセプト画像の背景を自動的に削除します。
プロトタイプ画像自体が透明性を持って返されるかどうかを制御する同名のプロトタイプパラメータ（デフォルト
false）とは別です。
- 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を圧縮し、model_urls.objの下にバンドルを返します。zip— ジェネレーターが生成するすべてのアーティファクトを圧縮し、model_urls.bundle_zipの下にバンドルを返します。
戻り値
レスポンスのresultプロパティには、新しく作成されたキーホルダー構築タスクのタスクidが含まれています。タスクの取得エンドポイントをポーリングするか、ストリームにサブスクライブしてタスクがSUCCEEDEDに達するまで待ち、model_urlsの単一エントリからアーティファクトをダウンロードします。
失敗モード
- Name
400 - Bad Request- Description
リクエストが受け入れられませんでした。一般的な原因:
- パラメータが不足しています:
input_task_idは必須です。 - 無効なUUID:
input_task_idが有効なUUIDではありません。 - 親が成功していません: 参照されたプロトタイプタスクがまだ
SUCCEEDEDに達していません。 - 候補がありません: プロトタイプタスクは成功しましたが、候補画像を生成しませんでした。
- 範囲外のオプション:
optionsフィールドの1つが許可された範囲または列挙セットの外にあります。
- パラメータが不足しています:
- Name
401 - Unauthorized- Description
認証に失敗しました。APIキーを確認してください。
- 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"
}
キーホルダータスクを取得する
有効なタスク id を指定して、プロトタイプまたはビルドタスクを取得します。URLパスはタスクのステージに一致する必要があります。/prototype/:id を通じて取得されたビルドタスクは 404 を返し、その逆も同様です。
キーホルダープロトタイプタスクオブジェクト および キーホルダービルドタスクオブジェクト を参照して、レスポンスの形状を確認してください。
パラメータ
- Name
- id
- Type
- path
- Description
取得するキーホルダータスクの一意の識別子。
戻り値
レスポンスにはキーホルダーのタスクオブジェクトが含まれます。形状は要求されたステージに依存します。
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).
キーホルダータスクをストリームする
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
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ソート可能な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オブジェクトのリファレンスについては、エラーを参照してください。
- 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=***"
]
}
キーホルダー ビルドタスクオブジェクト
キーホルダー ビルドタスクオブジェクトは、Meshyが追跡している作業単位であり、成功したプロトタイプタスクから最終的な3Dキーホルダーメッシュを生成します。このビルドは、プロトタイプのコンセプト画像に対して深度マップレリーフパイプラインを実行し、呼び出し元が要求した形式で単一のメッシュアーティファクトを公開します。
プロパティ
- 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。アーティファクト名でキー付けされています。ビルドリクエストの
output.formatで要求された形式に基づいて、常に正確に1つのエントリを含みます。キーは要求された形式に一致します：- 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=***"
}
}