Creative Lab — キーキャップ API

Meshyがキーキャップデザイン画像へ変換する元の写真です。現在サポートしている形式は .jpg、.jpeg、.png、.webp です。

形式は画像データをデコードして判定され、URLのファイル拡張子からは判定されません — 拡張子のないURLやリダイレクトするURLでも、バイト列がサポートされている形式にデコードできれば問題ありません。HTTPリダイレクトは追跡されます。EXIFの向き情報は正規化されるため、回転した状態のスマートフォン写真も見た目通りに使用されます。

制限: 各辺が最低 32 ピクセル、合計で最大 178,956,970 ピクセル、ダウンロード後で最大 20,000,000 バイトです。data URIの場合、この制限はデコード後のバイト数に適用されるため、元のファイル自体はそのサイズまで使用できます — base64テキストはおよそ3分の1大きくなりますが、それはリクエストボディのサイズに関係する話であり、この制限には関係しません。data URIは image/* のcontent typeと ;base64 を宣言する必要があります。

画像を指定する方法は2つあります:

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

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

true に設定すると、image_urls で返される表示用レンダーは、背景が除去された透明RGBA PNGとなり、任意の背景に合成できます。

これは表示用レンダーにのみ適用されます。buildエンドポイントが使用する候補には影響しないため、3Dの結果はどちらの場合でも同一です。

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

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

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

アカウントが無料プランである(タスクの作成には有料プランが必要です)か、クレジットが不足しています。

入力画像が知的財産moderationによってフラグ付けされました。

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

予期しないサーバー側のエラーが発生しました — 例えばcontent-moderationサービスが利用できなかった、入力画像のステージングに失敗した、またはタスクを作成できなかった場合です。この場合タスクは作成されないため、再試行しても安全です。

この同じOpenAPIエンドポイント経由で作成されたプロトタイプタスクのタスクIDです。プロトタイプは同じMeshyアカウントによって作成されている必要があり、SUCCEEDEDに到達している必要があり、少なくとも1つのキャンディデートを生成している必要があります。

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

ビルド対象のキャンディデートで、成功したプロトタイプタスクのcandidate_ids配列から取得します。そのタスクに属している必要があり、それ以外の値は400で拒否されます。

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

ビルド対象のキーキャップベースです。現在利用可能な値はcherry-mx-1x1-r1(標準のCherry MXプロファイル1uキーキャップ)のみです。3〜5個の追加の主流な標準サイズが計画されていますが、カスタムサイズはサポートされていません。

スカルプトされたヘッドの目標サイズ(ミリメートル単位)です。その最長寸法がこの値にスケーリングされます。範囲: [10, 40]。おおよそ32.9を超える値は、ヘッドがベースの保護フットプリント制限に収まるように縮小される場合があるため、実際に提供される最長寸法はリクエストした値より小さくなることがあります。適用された値は現在タスクオブジェクトに反映されません——実際に受け取ったサイズを確認する必要がある場合は、ダウンロードしたモデル内のkeycap-headメッシュのバウンディングボックスを測定してください。

ヘッドをベースに配置する前に適用される垂直方向のオフセット(ミリメートル単位)です。範囲: [-5, 5]。

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

• パラメータの欠落: input_task_idとcandidate_idは必須です。
• 無効なUUID: input_task_idが有効なUUIDではありません。
• 親タスクが未完了: 参照されているプロトタイプタスクがまだSUCCEEDEDに到達していません。
• キャンディデートが存在しない: プロトタイプタスクは成功しましたが、キャンディデートを生成しませんでした。
• 不明なキャンディデート: candidate_idが入力タスクのキャンディデートのいずれでもありません。
• オプションが範囲外: optionsフィールドのいずれかが許可された範囲または列挙セットの外にありました。

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

アカウントが無料プランである(タスクの作成には有料プランが必要です)か、クレジットが不足しています。

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

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

予期しないサーバー側のエラーが発生しました——例えば、コンテンツmoderationサービスが利用できなかった、入力画像のステージングに失敗した、またはタスクを作成できなかった場合です。この場合タスクは作成されないため、再試行しても安全です。

取得するキーキャップタスクの一意の識別子。

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

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

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

キャンセル中に予期しないサーバー側のエラーが発生しました。タスクがキャンセルされたかどうかは不明です。再試行する前に読み直して確認してください。

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

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

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

ページサイズの上限。最大で 100 件まで指定できます。

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

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

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

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

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

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

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

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

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

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

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

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

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

このタスクによって消費されたクレジットの数です。SUCCEEDEDに達したタスクは、そのステージの全額が課金されます。作成されなかったタスク（リクエスト時の4xx、moderationによる拒否を含む）は一切課金されません。FAILEDに達したタスクは0を返します——非同期のmoderationブロックを含め、課金分は返金されます。DELETEによるキャンセルは、タスクがまだPENDINGの間のみ返金されます。すでにIN_PROGRESSのタスクは、作業が既に費やされているため課金されたままになります。

完成済みキーキャップデザインのレンダリング画像——候補が完成キーキャップとしてどのように見えるかをダウンロードできるURLです。1件のエントリのみを保持します。image_urls[i]はcandidate_ids[i]に対応します。タスクがSUCCEEDEDに達するまでは空です。このURLは表示のみを目的としており、ビルドエンドポイントはこれらのURLではなくcandidate_idsを消費します。model_urlsと同じURLのライフサイクル、つまり署名付きで、Authorizationヘッダーは不要、expires_atまで有効、タスクを再読み込みしても安定しています。

image_urlsと並行する、不透明な候補識別子です。選択したデザインに対応するエントリを、ビルドリクエストのcandidate_idとして渡してください。これらのidの形式についていかなる前提も置かないようにしてください。

タスクの一意な識別子。

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

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

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

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

タスクが作成されたときのタイムスタンプ（ミリ秒単位）。

タスクが開始されたときのタイムスタンプ（ミリ秒単位）。

タスクが終了したときのタイムスタンプ（ミリ秒単位）。

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

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

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

このタスクによって消費されたクレジット数。SUCCEEDED に達したタスクは、そのステージの全額が課金されます。作成されなかったタスク（リクエスト時の 4xx、moderationによる拒否を含む）は一切課金されません。FAILED に達したタスクは 0 を返します — 非同期のmoderationブロックを含め、課金は返金されます。DELETE によるキャンセルは、タスクがまだ PENDING の間のみ返金されます。すでに IN_PROGRESS になっているタスクは、作業が消費されているため課金されたままです。

生成されたモデルアーティファクトのダウンロード可能なURL。GLBとOBJバンドルはいずれも実世界のミリメートル単位、Y-upでエクスポートされ、キーキャップの前面は+Zを向きます。メッシュは keycap-head と keycap-base という名前になります。ベースがパターン塗りにフォールバックした場合、ステムの空洞用に3番目のメッシュ keycap-base-interior も存在します。メッシュが必ず2つだけであると仮定しないでください。

これらは署名付きURLです。Authorization ヘッダーを付けずに取得してください。これらは expires_at まで有効であり、これは finished_at から3日後です。この期間内にタスクを再読み込みしても、新たに署名されたURLではなく同一のURLが返されます。期限が切れる前に、必ず自分でファイルをダウンロードして保存してください。期限切れのリンクを更新する方法はありません。

中間プロセス画像のダウンロード可能なURLで、種類をキーとしています。model_urls と同じURLライフサイクルです：署名付きで、Authorization ヘッダーは不要、expires_at まで有効、タスクを再読み込みしても安定しています。現在発行される種類は以下の通りです：

• head_design — ビルドが使用した、選択されたキャンディデートのデザイン画像（常に存在します）。
• composite — 選択されたキャンディデートの完成キーキャップ表示レンダー（利用可能な場合に存在します）。
• base_canvas — 描画されたキーキャップベースのキャンバス（利用可能な場合に存在します）。

このキーセットは今後拡張される可能性があるものとして扱ってください。新しい種類が破壊的変更なしに追加される可能性があります。