Creative Lab キーキャップ API

キーキャップデザインに変換する写真を、公開URLまたはData URI（data:image/jpeg;base64,<your base64-encoded image data>）として指定します。

画像はJPG、JPEG、PNG、またはWebPファイルで、最大20 MB（20,000,000バイト）である必要があります。各辺は少なくとも32ピクセル必要で、画像の総ピクセル数は最大178,956,970ピクセルです。この制限を超える画像は400を返します。

Meshyは画像データから形式を検出します。URLのファイル拡張子からは検出しません。拡張子のないURLも機能し、MeshyはHTTPリダイレクトに従います。Meshyは EXIF の向き情報を適用するため、回転したスマートフォン写真も見た目どおりに出力されます。

Data URIはbase64エンコードされ、data:image/png;base64,...のような画像タイプである必要があり、デコードされた画像はJPEG、PNG、またはWebPである必要があります。20 MBの制限はデコード後の画像に適用されるため、base64テキストは約3分の1大きくなる場合があります。

タスクの名前で、最大100文字です。タスクのnameフィールドに返されます。これより長い名前を指定すると400が返されます。

プロトタイプ画像の背景を除去するかどうかを指定します。trueを指定すると透過RGBA PNGが返されるため、任意の背景にキーキャップを配置できます。Meshyが背景を除去できない場合は、背景付きの画像を返し、タスクは引き続き成功します。

buildが3Dに変換するヘッド部分のデザインは、いずれの場合も背景を保持します。buildはimage_urlsの画像からキーキャップのベースを描画し、trueを送信した場合はその背景を除いて描画します。buildはその画像をprocess_image_urls.compositeとして返します。

リクエストを実行できません。たとえば次のような場合です。

• image_urlが指定されていない。
• 画像がJPG、JPEG、PNG、またはWebPファイルではない。
• 画像が小さすぎる、20 MBを超えている、または最大ピクセル数を超えている。
• Meshyが画像をダウンロードできない。たとえばURLが404を返す場合やタイムアウトする場合。
• Data URIが有効なbase64ではない。
• 画像がNSFWとしてフラグ付けされた。

エラーメッセージには、検出された問題の内容が記載されています。リクエストを修正してから、再度送信してください。

APIキーが指定されていないか、無効です。Authorizationヘッダーを確認してください。

次のいずれかに該当します。

• アカウントのクレジットが不足している。
• APIキー、ワークスペース、またはメンバーがクレジット上限に達した。
• アカウントが無料プランである。

クレジットとプランを確認してから、再試行してください。

あなたのチームでIPフィルタリングが有効になっており、Meshyがその画像をサードパーティの知的財産としてフラグ付けしました。使用権を持つ画像を送信してください。

次のいずれかの上限に達しました。

• レート制限で許可されている数を超えるリクエストを送信した。数秒待ってから再試行してください。レート制限を参照してください。
• キューに入っている、または実行中のタスクが多すぎる。いくつか完了するのを待ってから再試行してください。
• クレジットを使い切った無制限プランで、クレジットなしで実行できるタスク数に達した。タスクが完了するのを待つか、クレジットを追加してください。

Meshyでサーバーエラーが発生しました。たとえばコンテンツmoderationや知的財産チェックを実行できなかった、またはMeshyが画像を保存できなかった場合です。Meshyはタスクを作成せず、課金されたクレジットがあれば返金します。リクエストを再試行してください。

ビルド対象のプロトタイプタスクのIDです。POST /openapi/creative-lab/keycap/v1/prototypeであなたのアカウントが作成した、ステータスがSUCCEEDEDのタスクである必要があります。

APIから作成されたあなたのKeycapプロトタイプタスクに一致しないIDは、ウェブアプリで作成されたプロトタイプを含め、404を返します。

プロトタイプタスクのcandidate_ids配列から、ビルド対象のキャンディデートです。その配列に含まれない値は400を返します。

タスクの名前です。最大100文字です。タスクのnameフィールドに返されます。これより長い名前は400を返します。

ビルドの基になるキーキャップベースです。唯一の値はcherry-mx-1x1-r1で、標準的なCherry MXプロファイルの1uキーキャップです。カスタムサイズはサポートされておらず、それ以外の値は400を返します。

ヘッドの最長寸法のサイズをミリメートル単位で指定します。10から40までの範囲です。Meshyは、最長寸法がこの値と一致するようにヘッドをスケーリングします。範囲外の値は400を返します。

約32.9を超える値の場合、Meshyはベースの保護用フットプリント制限にヘッドが収まるようにサイズを縮小することがあります。その結果、ヘッドが要求したものより小さく仕上がることがあります。タスクオブジェクトは、Meshyが適用したサイズを返しません。確認するには、モデル内のkeycap-headメッシュのバウンディングボックスを測定してください。

Meshyがヘッドをベースに座らせる前に適用する垂直オフセットをミリメートル単位で指定します。-5から5までの範囲です。範囲外の値は400を返します。

リクエストを実行できません。例えば:

• input_task_idが欠落しているか、有効なタスクIDではない。
• プロトタイプタスクのステータスがSUCCEEDEDではない。まだ実行中の場合は、待ってから再試行してください。失敗またはキャンセルされた場合は、新しいプロトタイプタスクを作成してください。
• プロトタイプタスクは成功したが、キャンディデートがない。新しいプロトタイプタスクを作成してください。
• candidate_idが欠落しているか、プロトタイプタスクのcandidate_idsに含まれていない。その配列内の値を送信してください。
• options内のフィールドが範囲外であるか、base_modelが利用可能な値ではない。

エラーメッセージには、どの問題が見つかったかが示されます。

APIキーが欠落しているか無効です。Authorizationヘッダーを確認してください。

以下のいずれかに該当します:

• アカウントに十分なクレジットがない。
• APIキー、ワークスペース、またはメンバーがクレジット上限に達した。
• アカウントが無料プランである。

クレジットとプランを確認してから、再試行してください。

input_task_idが、あなたのアカウントがAPIで作成したどのKeycapプロトタイプタスクとも一致しません。ウェブアプリで作成されたプロトタイプも404を返します。プロトタイプ作成レスポンスのresult IDを送信してください。

以下のいずれかの制限に達しました:

• レート制限で許可されている数を超えるリクエストを送信した。数秒待ってから再試行してください。Rate limitsを参照してください。
• キューに入っているか実行中のタスクが多すぎる。いくつか完了するのを待ってから再試行してください。
• クレジットが残っていない無制限プランで、クレジットなしで実行できるタスク数の上限に達した。タスクが完了するのを待つか、クレジットを追加してください。

サーバーエラーのため、Meshyはタスクを作成できませんでした。Meshyは課金されたクレジットを払い戻します。リクエストを再試行してください。

作成レスポンスから取得したタスクID。

id が有効なタスクIDではありません。作成レスポンスの result IDを送信してください。

あなたのチームでIPフィルタリングが有効になっており、Meshyがプロトタイプタスクの画像を第三者の知的財産としてフラグ付けしました。ビルドタスクおよびEnterpriseプランのチームでは、このエラーは発生しません。使用権のある画像からプロトタイプタスクを作成してください。

このIDのKeycapタスクがあなたのアカウントに属していないか、タスクのステージがパスと一致していません。IDを確認し、タスクに合わせて /prototype または /build を使用してください。

Meshyは知的財産チェックを実行できませんでした。リクエストを再試行してください。

キャンセルするタスクの ID。

次のいずれかに該当します：

• id が有効なタスク ID ではありません。作成レスポンスの result ID を送信してください。
• タスクはすでに最終ステータス（SUCCEEDED、FAILED、または CANCELED）であるため、キャンセルできません。

この ID の Keycap タスクがあなたのアカウントに属していないか、タスクのステージがパスと一致していません。ID を確認し、タスクに合わせて /prototype または /build を使用してください。

タスクのキャンセル中に Meshy でサーバーエラーが発生したため、タスクがキャンセルされたかどうかは不明です。再試行する前に、タスクを取得してその status を確認してください。

作成レスポンスから取得したタスクID。

一覧取得するステージ。prototype または build。

返すページ。1 から 255 まで。0 は最初のページを返します。0 から 255 の範囲外の値は 400 を返します。

1ページあたりのタスク数。最大 100。101 から 255 の値は100件のタスクを返し、0 はデフォルト値を使用します。0 から 255 の範囲外の値は 400 を返します。

ソート順。

利用可能な値:

• -created_at: 新しい順
• +created_at: 古い順

タスクID。フォーマットに依存しないでください。

タスクタイプ。常に creative-lab-keycap-prototype です。

タスク作成時に送信した name。送信しなかった場合は "" です。

タスクのステータス。

使用可能な値：

• PENDING：キューで待機中
• IN_PROGRESS：結果を生成中
• SUCCEEDED：最終状態、結果あり
• FAILED：最終状態、理由は task_error に記載
• CANCELED：最終状態、結果なし

作業の完了率（0 から 100 まで）。タスクが開始するまでは 0 で、成功すると 100 になります。

タスクが作成された時刻（Unixミリ秒）。

ワーカーがタスクを開始した時刻（Unixミリ秒）。それまでは null です。

タスクが最終ステータスに達した時刻（Unixミリ秒）。それまでは null です。

タスクの結果が期限切れになる時刻（Unixミリ秒）。finished_at の3日後、またはタスクが完了するまでは created_at の3日後です。APIの結果を無期限に保持するEnterpriseアカウントの場合、約100年後になります。アセット保持期間を参照してください。

タスクが PENDING の間のキュー内での位置。1 は次に開始することを意味します。タスクがキューを離れると 0 になり、リスト結果では常に 0 です。

タスクが失敗した理由。status が FAILED でない限り null です。エラーを参照してください。

タスクに対して請求されたクレジット数（返金後）。エラーを返すリクエストには課金されません。失敗したタスクはMeshyが返金するため 0 になります。キャンセルによる返金は、タスクが PENDING の間のみ行われます。Meshyが課金情報を読み取れない場合、getまたはstreamのレスポンスではこのフィールドが省略され、listリクエストは 500 を返します。その場合はリクエストを再試行してください。

完成したキーキャップの画像のダウンロードURL。タスクが成功すると配列にはURLが1つ含まれ、それまでは空です。image_urls[i] は candidate_ids[i] の候補を示します。

これらのURLは表示用です。buildエンドポイントはURLではなく candidate_ids のエントリを受け取ります。これらは署名付きURLのため、Authorization ヘッダーなしで取得してください。expires_at まで有効であり、タスクを再度取得しても同じURLが返されます。

候補のID。image_urls と同じ順序です。候補をビルドするには、そのIDをbuildリクエストの candidate_id として送信してください。これらのIDのフォーマットに依存しないでください。

タスクID。形式に依存しないでください。

タスクの種類。常に creative-lab-keycap-build です。

タスク作成時に送信した name。送信しなかった場合は "" です。

タスクのステータス。

使用可能な値：

• PENDING：キュー内で待機中
• IN_PROGRESS：結果を生成中
• SUCCEEDED：最終状態。結果あり
• FAILED：最終状態。理由は task_error に記載
• CANCELED：最終状態。結果なし

作業の完了率を示す 0 から 100 までの値です。タスクが開始するまでは 0、成功すると 100 になります。

タスクが作成された時刻（Unixミリ秒）。

ワーカーがタスクを開始した時刻（Unixミリ秒）。それまでは null です。

タスクが最終ステータスに到達した時刻（Unixミリ秒）。それまでは null です。

タスクの結果が期限切れになる時刻（Unixミリ秒）。finished_at の3日後、またはタスクが完了するまでは created_at の3日後です。APIの結果を無期限に保持するEnterpriseアカウントの場合、約100年後になります。アセット保持期間を参照してください。

タスクが PENDING の間のキュー内での位置。1 は次に開始することを意味します。タスクがキューを離れた後は 0 になり、リスト結果では常に 0 です。

タスクが失敗した理由。status が FAILED でない限り null です。エラーを参照してください。

返金分を差し引いた後に、タスクに対して請求されたクレジット数。エラーを返すリクエストには課金されません。失敗したタスクはMeshyが返金するため 0 です。キャンセルによる返金は、タスクが PENDING の間のみ行われます。Meshyが課金額を読み取れない場合、getまたはstreamのレスポンスではこのフィールドが省略され、listリクエストでは 500 が返されます。その場合は、リクエストを再試行してください。

3Dモデルのダウンロード用URLです。Meshyは、GLBファイルとOBJバンドルを、ミリメートル単位の実寸スケールで、Y-up、キーキャップの正面が+Z方向を向くようにエクスポートします。

モデルには keycap-head と keycap-base という名前のメッシュがあります。Meshyがベースのパターン塗りつぶしにフォールバックした場合、モデルにはステム空洞用の keycap-base-interior メッシュも含まれます。モデルに必ず2つのメッシュしかないとは想定しないでください。

これらは署名付きURLのため、Authorization ヘッダーなしで取得してください。expires_at まで有効であり、それまでにタスクを再取得すると同じURLが返されます。期限切れのURLは更新できないため、それより前にファイルをダウンロードして保存してください。

ビルドの各ステップから得られた画像のダウンロード用URLで、種類ごとにキー付けされています。model_urls と同様、これらは署名付きURLのため、Authorization ヘッダーなしで取得してください。expires_at まで有効であり、タスクを再取得すると同じURLが返されます。

次のキーを持つ場合があります：

• head_design：選択されたキャンディダートのデザイン画像。ビルドがこれを3D化しました。常に存在します。
• composite：選択されたキャンディダートの完成したキーキャップの画像。ビルドはこの画像からベースを塗装しました。存在しない場合があります。
• base_canvas：塗装されたキーキャップベース。存在しない場合があります。

Meshyがキーを追加する場合があるため、認識できないキーは無視してください。