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>。

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

これはダッシュボードやタスク一覧でタスクにラベルを付けるためのものです。キーホルダーに刻印されるわけではありません — 刻印には name_text を使用してください。

ペットや人物の名前など、キーホルダーに刻印するテキストです。最大10文字で、バイト数ではなくUnicode文字数としてカウントされるため、10文字の中国語、日本語、韓国語の名前も受け付けられます。省略すると、刻印なしのキーホルダーが生成されます。

テキストが使用される前に、前後の空白はトリムされ、目に見えない書式制御文字は除去されます。結果として得られる値はprototype task objectの name_text として返されるため、ビルド段階の料金を支払う前に、実際に刻印される内容を正確に確認できます。

刻印はこの段階、すなわちプロトタイプ段階で適用されます。ビルド段階はこれを自動的に継承し、独自の name_text は受け付けません。

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

これはこのエンドポイントが返す画像のみを制御します。同名のビルドオプション(デフォルト true)とは別物で、そちらはリリーフ加工前の背景除去を制御します。

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

• パラメータの欠落: image_url は必須です。
• 無効な画像形式: 指定された image_url がサポートされている形式(.jpg、.jpeg、.png、.webp)ではありません。
• 画像サイズが範囲外: 画像が小さすぎる、最大ファイルサイズを超えている、または最大ピクセル数を超えています。
• 到達不能なURL: image_url をダウンロードできませんでした(404またはtimeout)。
• 無効なData URI: base64文字列の形式が不正です。
• 刻印が長すぎる: name_text が10文字を超えています。リクエストは切り詰められるのではなく拒否されるため、短縮された名前が刻印されたキーホルダーに対して課金されることはありません。
• コンテンツがフラグ付けされた: 入力画像がNSFWまたは知的財産moderationによってフラグ付けされたか、name_text の刻印がNSFW moderationによってフラグ付けされました。刻印はNSFWコンテンツについてのみスクリーニングされます — 知的財産のスクリーニングは画像に対して適用されます。

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

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

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

この同じOpenAPIエンドポイント経由で作成されたプロトタイプタスクのタスクID。プロトタイプは同じAPIキーで作成され、SUCCEEDEDに到達し、候補画像をちょうど1枚生成している必要があります。

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

表示用の任意のタスク名。最大100文字。

キーホルダーメダリオンの外形シルエット。使用可能な値：

• circle（デフォルト）
• rounded-rect
• hexagon
• shield
• star

キーホルダーの外接正方形の辺の長さ（ミリメートル）。範囲：(0, 400]。

ベースからのリリーフの最大高さ（ミリメートル）。範囲：[0, 20]。

押し出し前にリリーフに適用される垂直オフセット（ミリメートル）。範囲：[0, 20]。

リリーフ背後のフラットベースプレートの厚さ（ミリメートル）。範囲：[0, 20]。

メダリオンの背面を閉じた面として密閉するかどうか。開いたシェルにする場合はfalseを設定してください。

深度マップの値をリリーフの高さにマッピングする変換カーブ。使用可能な値：

• linear（デフォルト）
• gamma
• s-curve

変換カーブの形状パラメータ（relief_curveがgammaの場合のみ意味を持ちます）。範囲：(0, 10]。

深度マップの解釈を反転し、暗い領域がより高いリリーフになるようにします。

リリーフ抽出前に深度マップへ適用する平滑化の強度。範囲：[0, 10]。

relief_height_mmに加えて適用される垂直スケール乗数。範囲：(0, 10]。

深度マップ値のローパスしきい値。この値未満はゼロにクランプされます。範囲：[0, 1]。

リリーフ処理前に、プロトタイプのコンセプト画像の背景を自動的に除去します。

同名のプロトタイプパラメータ（デフォルトfalse）とは別のものです。そちらは、プロトタイプ画像自体を透明背景付きで返すかどうかを制御します。

エクスポートに使用されるメッシュ解像度。範囲：[64, 2048]。

ビルドから返されるアーティファクトバンドル。使用可能な値：

• glb（デフォルト）— model_urls.glbに単一のmodel.glbを返します。
• obj — model.obj + model.mtl + texture.pngをzip化し、model_urls.objにバンドルを返します。
• zip — ジェネレーターが出力するすべてのアーティファクトをzip化し、model_urls.bundle_zipにバンドルを返します。

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

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

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

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

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

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

取得するキーホルダータスクの一意の識別子です。

キャンセルするキーホルダータスクの一意の識別子。

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

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

ストリーミング対象のキーホルダータスクを識別する一意の識別子です。

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

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

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

並び替えの基準となるフィールドです。利用可能な値：

• +created_at: 作成時刻の昇順で並び替えます。
• -created_at: 作成時刻の降順で並び替えます。

タスクの一意な識別子です。実装の詳細としてタスクIDにはkソート可能なUUIDを使用していますが、この形式についていかなる前提も置かないようにしてください。

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

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

このキーホルダーに適用される刻印を、トリミングし不可視の書式文字を除去した後の文字列です。タスクが name_text を指定せずに作成された場合は存在しません。送信した内容と比較して、テキストがHTTPクライアントのエンコーディングを経ても正しく維持されているかを確認してください。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

生成されたアーティファクトのダウンロード可能なURLで、アーティファクト名をキーとします。常にちょうど1つのエントリを含み、それはビルドリクエストの output.format で指定された形式です。キーはリクエストされた形式と一致します。