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/* コンテンツタイプと ;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になり、任意の背景に合成できます。

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

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

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

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

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

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

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

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

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

Webアプリを通じて作成されたプロトタイプタスクは受け入れられません — ビルドエンドポイントは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が入力タスクの候補の1つではありません。
• 範囲外のオプション: optionsフィールドの1つが許可された範囲または列挙セットを超えました。

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

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

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

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

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

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

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

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

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

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

ストリームするキーキャップタスクの一意の識別子。

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

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

ページサイズの制限。最大許容は 100 アイテムです。

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

• +created_at: 作成時間で昇順にソート。
• -created_at: 作成時間で降順にソート。

タスクの一意の識別子。タスクIDにはkソート可能なUUIDを使用していますが、IDの形式については何も仮定しないでください。

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

タスクが作成されたときに提供されたタスク名。名前が提供されなかった場合は空の文字列です。

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

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

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

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

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

タスク結果の有効期限のタイムスタンプ（ミリ秒単位）。

先行タスクの数。

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

このタスクによって消費されたクレジットの数。SUCCEEDEDに達したタスクは、その段階の全額が請求されます。作成されなかったタスク（リクエスト時の4xx、モデレーション拒否を含む）は全く請求されません。FAILEDに達したタスクは0を返し、請求は返金されます（非同期のモデレーションブロックを含む）。DELETEによるキャンセルは、タスクがまだPENDINGの間のみ返金されます。すでにIN_PROGRESSのタスクは請求されたままです。なぜなら、作業がすでに行われているからです。

完成したキーキャップデザインレンダーのダウンロード可能なURL — 候補が完成したキーキャップとしてどのように見えるかを示します。単一のエントリを保持します。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のいずれかです。

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

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

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

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

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

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

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

このタスクによって消費されたクレジットの数。SUCCEEDEDに達したタスクは、そのステージの全額が課金されます。作成されなかったタスク（リクエスト時の4xx、モデレーション拒否を含む）は一切課金されません。FAILEDに達したタスクは0を返し、課金は返金され、非同期モデレーションブロックも含まれます。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 — 塗装されたキーキャップベースキャンバス（利用可能な場合に存在）。

キーセットはオープンエンドとして扱ってください。新しい種類が破壊的変更なしに追加される可能性があります。