Creative Lab — ランプ API

目的のランプシェードの被写体を説明するテキストプロンプト。image_url を省略する場合は必須です。最大 800 文字です。

Meshy がランプシェードの視覚的な参照として使用する元写真。text を省略する場合は必須です。現在、.jpg、.jpeg、.png、.webp 形式をサポートしています。

画像の提供方法は 2 つあります。

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

image-to-3D パス用の被写体カテゴリのヒント。利用可能な値:

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

text-to-3D パスでは無視されます。

表示目的の任意のタスク名。最大 100 文字です。

リクエストは受け付けられませんでした。一般的な原因:

• パラメータ不足: text または image_url のいずれか一方が必須です。
• 両方が指定されている: text と image_url の両方を渡すと拒否されます — これらは相互に排他的です。
• 無効な画像形式: 指定された image_url はサポートされている形式（.jpg、.jpeg、.png、.webp）ではありません。
• 画像サイズが範囲外: 画像が小さすぎる、最大ファイルサイズを超えている、または最大ピクセル数を超えています。
• 到達できない URL: image_url をダウンロードできませんでした（404 またはタイムアウト）。
• 無効な Data URI: base64 文字列の形式が不正です。
• コンテンツがフラグ付けされた: 入力画像が NSFW または知的財産のモデレーションによってフラグ付けされました。
• テキストが長すぎる: text が 800 文字を超えています。
• 無効な image_subject: character / landscape のいずれでもありません。

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

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

レート制限を超えています。

この同じ OpenAPI endpoint 経由で作成されたプロトタイプタスクのタスク ID です。プロトタイプは同じ API key で作成されている必要があり、SUCCEEDED に到達していて、候補画像を正確に 1 つ生成している必要があります。

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

表示目的の任意のタスク名です。最大 100 文字です。

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

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

プリントがベッド上に置けるように、上部で平坦化するランプシェード高さの割合です。範囲: [1, 100]。

ランプシェードと一緒にベースディスクを出力するかどうか（および何を出力するか）を決定する光源フィクスチャプリセットです。利用可能な値:

• bambu_mh001_60mm（デフォルト）— 互換性のある光源フィクスチャ用にサイズ調整された 60 mm のベースディスクを出力します。結果には model_urls.base_stl が含まれます。
• none — フィクスチャなし、ベースディスクなし。model_urls.base_stl は省略されます。

ランプシェード中心に対するフィクスチャ切り抜きの水平方向 X 軸オフセット（ミリメートル単位）です。light_source_preset ≠ none の場合にのみ意味があります。範囲: [-80, 80]。

ランプシェード底面に対するフィクスチャ切り抜きの垂直方向 Z 軸オフセット（ミリメートル単位）です。範囲: [-80, 80]。

処理前にインポートされたメッシュへ適用される X 軸周りの回転（度単位）です。範囲: [-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）を 1 つの zip にパッケージし、model_urls.bundle_zip の下で返します。

リクエストは受け付けられませんでした。一般的な原因:

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

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

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

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

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

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

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

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

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

ストリーミングするランプタスクの一意の識別子。

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

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

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

ソートに使用するフィールドです。利用可能な値:

• +created_at: 作成時刻の昇順でソートします。
• -created_at: 作成時刻の降順でソートします。

タスクの一意の識別子です。実装の詳細としてタスク ID には k-sortable UUID を使用していますが、id の形式についてはいかなる仮定もしないでください。

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

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

タスクのステータスです。指定可能な値は PENDING、IN_PROGRESS、SUCCEEDED、FAILED、CANCELED のいずれかです。

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

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

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

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

タスク結果の有効期限が切れる時刻のタイムスタンプ（ミリ秒）です。

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

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

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

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

タスクの一意の識別子。

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

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

タスクのステータス。可能な値は PENDING、IN_PROGRESS、SUCCEEDED、FAILED、CANCELED のいずれかです。

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

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

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

タスクが完了した時刻のタイムスタンプ（ミリ秒）。

タスク結果の有効期限が切れる時刻のタイムスタンプ（ミリ秒）。

先行タスクの数。ステータスが PENDING の場合にのみ意味があります。

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

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

生成されたアーティファクトのダウンロード可能な URL。アーティファクト名をキーとします。キーのセットは output.format と options.light_source_preset によって異なります。