Creative Lab — ランプ API

Meshy がランプシェードの視覚的な参照として使用するソース写真です。現在、.jpg、.jpeg、.png、.webp形式をサポートしています。

画像を提供する方法は2つあります：

• 公開アクセス可能なURL: インターネット上から公開アクセス可能なURL。
• Data URI: 画像のbase64エンコードされたdata URI。Data URIの例: data:image/jpeg;base64,<your base64-encoded image data>。

スタイライゼーションのpromptを選択するための被写体カテゴリのヒントです。利用可能な値：

• character（デフォルト） — 単一のキャラクター／オブジェクト被写体（フィギュア、動物、マスコットなど）。
• landscape — 屋外シーン／パノラマ被写体（山、都市景観、森など）。

表示用のオプションのタスク名です。最大100文字。

trueに設定すると、プロトタイプ画像は背景が削除された透明なRGBA PNGとして返されるため、被写体を任意の背景に合成できます。

リクエストが受け付けられませんでした。よくある原因：

• パラメータの不足: image_urlが必須です。
• 無効な画像形式: 指定されたimage_urlがサポートされている形式（.jpg、.jpeg、.png、.webp）ではありません。
• 画像サイズが範囲外: 画像が小さすぎる、最大ファイルサイズを超えている、または最大ピクセル数を超えています。
• URLに到達できない: image_urlをダウンロードできませんでした（404またはtimeout）。
• 無効なData URI: base64文字列が不正な形式です。
• コンテンツがフラグ付けされた: 入力画像がNSFWまたは知的財産のmoderationによってフラグ付けされました。
• 無効なimage_subject: character／landscapeのいずれでもありません。

認証に失敗しました。APIキーを確認してください。

このタスクを実行するためのクレジットが不足しています。

レート制限を超えました。

この同じOpenAPIエンドポイント経由で作成されたプロトタイプタスクのタスクID。プロトタイプは同じAPIキーで作成され、SUCCEEDED に到達していて、3Dモデルを生成している必要があります。

webapp経由で作成されたプロトタイプタスクは受け付けられません — ビルドエンドポイントは POST /openapi/creative-lab/lamp/v1/prototype によって生成されたプロトタイプタスクのみを受け付け、それ以外のソースは 404 で拒否します。

表示用のオプションのタスク名。最大100文字。

ランプシェードのバウンディングボックスの目標最大寸法（ミリメートル単位）。メッシュはこれに合わせて一様にスケーリングされます。範囲: [50, 400]。

中空のランプシェードの肉厚（ミリメートル単位）。範囲: (0, 10]。

底面でフラットにカットされるモデル高さのパーセンテージ。これにより、ランプシェードはプリントベッドの上に置かれ、フィクスチャ用の開口部が生まれます。範囲: [1, 100]。

底面の構築方法を決定する光源フィクスチャプリセット。利用可能な値：

• bambu_mh001_60mm（デフォルト） — 底面が開いたランプシェードと、60mmのフィクスチャ穴を備えたベースプレート（いずれも model_urls.lamp_stl に含まれます）、およびフィクスチャマウントが model_urls.base_stl として提供されます。
• none — 単一の密閉されたランプシェードが model_urls.lamp_stl に含まれます。model_urls.base_stl は省略されます。

ランプシェードの中心を基準とした、ベースプレート上のフィクスチャ穴のX軸方向のオフセット（ミリメートル単位）。light_source_preset が none でない場合のみ意味を持ちます。範囲: [-80, 80]。

ランプシェードの中心を基準とした、ベースプレート上のフィクスチャ穴のZ軸（奥行き）方向のオフセット（ミリメートル単位）。light_source_preset が none でない場合のみ意味を持ちます。範囲: [-80, 80]。

処理前にモデルに適用されるX軸周りの回転（度単位）。3つの回転はモデルの中心を基準としたXYZオイラー角として適用されます。範囲: [-360, 360]。

処理前にインポートされたメッシュに適用されるY軸周りの回転（度単位）。範囲: [-360, 360]。

処理前にインポートされたメッシュに適用されるZ軸周りの回転（度単位）。範囲: [-360, 360]。

true かつ output.format が zip の場合、バンドル内にランププロセッサーの result.json（パイプライン名、警告、成果物のパス）を含めます。output.format が stl の場合は無視されます。

ビルドから返される成果物バンドル。利用可能な値：

• stl（デフォルト） — model_urls.lamp_stl（ランプシェード。フィクスチャプリセットが設定されている場合はベースプレートも含む）を返し、light_source_preset が none でない場合はさらに model_urls.base_stl を返します。
• zip — プロセッサーが生成するすべての成果物（lamp.stl、オプションの base.stl、オプションの result.json）を単一のzipにパッケージ化し、model_urls.bundle_zip として返します。

リクエストが受理できませんでした。よくある原因：

• パラメータ不足: input_task_id は必須です。
• 無効なUUID: input_task_id が有効なUUIDではありません。
• 親タスク未成功: 参照されているプロトタイプタスクがまだ SUCCEEDED に到達していません。
• モデルなし: プロトタイプタスクは成功しましたが、3Dモデルを生成しませんでした。
• オプションが範囲外: options のいずれかのフィールドが許容される範囲または列挙値のセットから外れています。

認証に失敗しました。APIキーを確認してください。

このタスクを実行するにはクレジットが不足しています。

参照されているプロトタイプタスクが存在しない、別のユーザーに属している、またはwebapp経由で作成されたものです（APIモードで作成されたプロトタイプタスクのみがビルドに連鎖できます）。

レート制限を超過しました。

取得するランプタスクの一意の識別子です。

キャンセルするランプタスクの一意の識別子。

タスクがすでに終了状態にあり、キャンセルできません。

タスクが存在しない、別のユーザーに属している、またはそのステージがURLパスと一致しません。

ストリーミング対象のランプタスクを識別する一意のIDです。

prototypeまたはbuildのいずれかです。このコレクションはURLに一致するステージのタスクのみを返します。/prototypeを取得した場合、ビルドタスクが返されることはなく、その逆も同様です。

ページネーション用のページ番号です。

ページサイズの上限です。最大で50件まで許可されます。

並べ替えに使用するフィールドです。使用可能な値：

• +created_at：作成日時の昇順で並べ替えます。
• -created_at：作成日時の降順で並べ替えます。

タスクの一意な識別子です。タスクIDには実装の詳細としてk-sortable UUIDを使用していますが、このidの形式について何らかの前提を置くべきではありません。

タスクの種類です。値は creative-lab-lamp-prototype です。

タスク作成時に指定されたタスク名です。名前が指定されていない場合は空文字列になります。

タスクのステータスです。取り得る値は PENDING、IN_PROGRESS、SUCCEEDED、FAILED、CANCELED のいずれかです。

タスクのprogressです。タスクがまだ開始されていない場合、このプロパティは 0 になります。タスクが成功すると、これは 100 になります。

タスクが作成された時刻のタイムスタンプ（ミリ秒）です。

タスクが開始された時刻のタイムスタンプ（ミリ秒）です。タスクがまだ開始されていない場合、このプロパティは 0 になります。

タスクが終了した時刻のタイムスタンプ（ミリ秒）です。タスクがまだ終了していない場合、このプロパティは 0 になります。

タスクの結果が失効する時刻のタイムスタンプ（ミリ秒）です。

先行するタスクの数です。

失敗したタスクのエラー詳細です。task_error オブジェクトの完全なリファレンスについては、エラーを参照してください。

このタスクによって消費されたクレジット数です。タスクのステータスが PENDING、IN_PROGRESS、または SUCCEEDED の場合に存在します。FAILED タスクの場合は 0 を返します（失敗時にはクレジットが返還されます）。

コンセプト画像から生成された3Dモデルのダウンロード可能なURLです。タスクが成功すると存在するようになり、それまでは {} です。

3Dモデルのレンダリングプレビューへのダウンロード可能なURLです。タスクが成功するまでは空文字列です。

このprototypeタスクによって生成されたコンセプト画像候補のダウンロード可能なURLです。現在、APIは常にちょうど1つの候補を返しますが、このフィールドは配列であるため、将来的な改訂で破壊的変更を伴わずに複数の候補を提供できるようになっています。

タスクの一意の識別子です。

タスクのタイプです。値は creative-lab-lamp-build です。

タスク作成時に指定されたタスク名です。名前が指定されなかった場合は空文字列になります。

タスクのステータスです。取り得る値は PENDING、IN_PROGRESS、SUCCEEDED、FAILED、CANCELED のいずれかです。

タスクの progress です。タスクがまだ開始されていない場合、このプロパティは 0 になります。タスクが成功すると 100 になります。

タスクが作成された時刻のタイムスタンプ（ミリ秒単位）です。

タスクが開始された時刻のタイムスタンプ（ミリ秒単位）です。

タスクが終了した時刻のタイムスタンプ（ミリ秒単位）です。

タスクの結果が失効する時刻のタイムスタンプ（ミリ秒単位）です。

先行タスクの件数です。ステータスが PENDING の場合にのみ意味を持ちます。

失敗したタスクのエラー詳細です。task_error オブジェクトの完全なリファレンスについては、エラーを参照してください。

このタスクで消費された consumed_credits の数です。FAILED タスクの場合は 0 を返します（失敗時にはクレジットが返還されます）。

生成された成果物のダウンロード可能な URL で、成果物名をキーとします。キーの集合は output.format と options.light_source_preset によって異なります。