Creative Lab キーホルダー API

キーホルダーのコンセプト画像に変換する写真を、公開URLまたはdata URI（data:image/jpeg;base64,<your base64-encoded image data>）として指定します。

画像はJPG、JPEG、PNG、またはWebPファイルで、最大20MBである必要があります。

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

この名前はダッシュボードやタスク一覧でタスクにラベルを付けるためのもので、キーホルダー上には表示されません。キーホルダーに名前を入れるにはname_textを使用してください。

ペットや人物の名前など、キーホルダーに追加する名前で、最大10文字です。Meshyはバイト数ではなく文字数をカウントするため、10文字の中国語、日本語、または韓国語の名前も収まります。これより長い名前を指定すると400が返されます。名前のないキーホルダーにする場合は省略してください。

名前はキーホルダーの表面に、浮き出しや切り抜きの文字としてではなく、平らな色付きのディテールとして表示されます。

Meshyは前後の空白をトリムし、不可視の書式文字を除去します。prototypeタスクオブジェクトは結果をname_textとして返すため、ビルドの代金を支払う前にテキストを確認できます。

Meshyはprototype段階で名前を追加します。ビルドはそれをそのまま保持し、ビルドエンドポイントに送信されたname_textは無視されます。

prototype画像から背景を除去するかどうかです。trueにすると、メダリオン全体を保持した透明なRGBA PNGが返されるため、任意の背景に配置できます。ビルドも背景のない画像から開始されます。Meshyが背景を除去できない場合は、背景付きの画像が返され、それでもタスクは成功します。

ビルドのremove_backgroundオプションはこれとは別です。

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

• image_urlがありません。
• 画像がJPG、JPEG、PNG、またはWebPファイルではありません。
• 画像が小さすぎる、20MBを超えている、または最大ピクセル数を超えています。
• 例えばURLが404を返す、またはタイムアウトするなど、Meshyが画像をダウンロードできません。
• data URIが有効なbase64ではありません。
• name_textが10文字を超えています。Meshyは短縮するのではなく拒否し、リクエストの料金は請求されません。
• 画像またはname_textがNSFWとしてフラグ付けされました。

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

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

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

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

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

チームでIP Filteringが有効になっており、Meshyがその画像を第三者の知的財産としてフラグ付けしました。使用権を持つ画像を送信してください。Meshyは画像のみを知的財産についてチェックし、name_textはチェックしません。

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

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

Meshyでサーバーエラーが発生しました。例えば、画像の知的財産チェックを実行できなかった場合などです。Meshyはタスクを作成せず、請求済みのクレジットがあれば払い戻します。リクエストを再試行してください。

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

あなたのAPI経由のKeychainプロトタイプタスクに一致しないIDは404を返します。これはウェブアプリで作成したプロトタイプも含みます。

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

Meshyが被写体からアウトラインをトレースしない場合の、キーホルダーのアウトラインです。remove_backgroundがfalseの場合、または被写体のアウトラインを検出できない場合にMeshyが使用します。

利用可能な値：

• circle
• rounded-rect
• hexagon
• shield
• star

キーホルダーの外接正方形の辺の長さで、単位はミリメートル、最大400です。0を指定するとデフォルト値が使われます。

ベースからのレリーフの最大高さで、単位はミリメートル、0から20までです。

レリーフをどれだけ下げるかで、単位はミリメートル、0から20までです。Meshyはレリーフの高さ全体からこの値を差し引き、ベースまで下げます。

レリーフの背後にある平らなベースプレートの厚さで、単位はミリメートル、0から20までです。

キーホルダーの背面を閉じるかどうかです。falseにすると、シェルのように背面が開いた状態になります。

デプスマップの値をレリーフの高さにマッピングするカーブです。

利用可能な値：

• linear
• gamma
• s-curve

カーブの強さで、最大10です。gammaとs-curveのカーブで使用され、linearでは無視されます。0を指定するとデフォルト値が使われます。

デプスマップを反転し、暗い領域をより高いレリーフにするかどうかです。

Meshyがレリーフを構築する前にデプスマップをどの程度平滑化するかで、0から10までです。

アウトライン内でレリーフとそのテクスチャを中心を基準にどの程度拡大するかで、最大10です。1を超える値は被写体を拡大し、1未満の値は縮小します。レリーフの高さは変わりません。0を指定するとデフォルト値が使われます。

これより下のデプスマップ値をMeshyが深さゼロに設定するしきい値で、0から1までです。

被写体からキーホルダーのアウトラインをトレースし、キーホルダーが被写体の形状に沿うようにするかどうかです。falseにすると、代わりにbadge_shapeのアウトラインが使われます。被写体のアウトラインを検出できない場合も、Meshyはbadge_shapeを使用します。

これはプロトタイプのremove_backgroundパラメータとは別物で、そちらはプロトタイプ画像の背景を透過にするかどうかを設定するものです。

エクスポートされるモデルのメッシュ解像度で、64から512までです。Meshyは512ピクセルのデプスマップからジオメトリを構築するため、これより細かいメッシュにしても詳細は増えず、面数だけが増えます。0を指定するとデフォルト値が使われます。

ビルドが返すファイル形式です。

利用可能な値：

• glb：model_urls.glb内の1つのmodel.glbファイル
• obj：model_urls.obj内の、model.obj、model.mtl、texture.pngを含むzipファイル
• zip：model_urls.bundle_zip内の、Meshyが生成するすべてのファイルを含むzipファイル

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

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

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

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

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

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

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

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

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

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

作成レスポンスに含まれるタスク ID です。

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

あなたのチームでIP Filteringが有効になっており、Meshy が prototype タスクの画像をサードパーティの知的財産としてフラグ付けしました。build タスクおよび Enterprise プランのチームではこのエラーは発生しません。使用権を持つ画像から prototype タスクを作成してください。

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

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

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

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

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

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

create応答から取得したタスクID。

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

返すページ番号。1 から 255 まで。0 を指定すると最初のページが返されます。0 から 255 の範囲外の値を指定すると 400 が返されます。

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

ソート順。

利用可能な値:

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

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

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

タスク作成時に送信したname、何も送信しなかった場合は""になります。

空白をトリムし、不可視の書式制御文字を除去した後に、Meshyがキーホルダーに追加した名前です。name_textを送信しなかった場合は省略されます。HTTPクライアントがテキストを正しくエンコードしたことを確認するには、送信した値と比較してください。

タスクのステータス。

使用可能な値:

• 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つ入り、それまでは空です。

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

タスクの種類。常に creative-lab-keychain-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 またはストリームのレスポンスではこのフィールドが省略され、リストリクエストは 500 を返します。その場合はリクエストを再試行してください。

モデルファイルのダウンロードURL。リクエストした output.format に対応する1つのエントリがあります。タスクが成功するまでは {} です。