Creative Lab — Lamp 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モデルを生成している必要があります。

webアプリ経由で作成されたプロトタイプタスクは受け付けられません。ビルドエンドポイントは 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キーを確認してください。

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

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

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

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

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

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

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

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

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

ページネーションのためのページ番号。

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

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

• +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 オブジェクトの完全なリファレンスについては、Errors を参照してください。

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

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

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

このプロトタイプタスクによって生成されたコンセプト画像の候補のダウンロード可能な URL です。現在、API は常に厳密に1つの候補を返しますが、このフィールドは配列になっており、将来のリビジョンで破壊的変更なしに複数の候補を提供できるようになっています。

タスクの一意の識別子。

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

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

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

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

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

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

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

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

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

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

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

生成された成果物のダウンロード可能なURL。成果物名をキーとします。キーのセットは output.format と options.light_source_preset に依存します。