Creative Lab — Fidget Pixel API

Meshy がピクセル化する元の写真。現在サポートしている形式は .jpg、.jpeg、.png、.webp です。

形式は画像データをデコードすることで検出され、URL のファイル拡張子からは判定されません — 拡張子のない URL や、リダイレクトする URL であっても、バイトデータがサポート対象の形式にデコードできる限り問題なく動作します。HTTP リダイレクトはたどられます。

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

• 公開アクセス可能な URL: インターネット上から公開アクセス可能な URL。
• Data URI: 画像を base64 エンコードした data URI。data URI の例: data:image/jpeg;base64,<your base64-encoded image data>。

写真に写っているものを指定します。ピクセル化のスタイルを選択するため、慎重に選んでください — この2つは見た目に明確な違いのある結果を生成します。指定可能な値:

• person — 被写体が人物(ポートレートまたは全身)の場合。被写体のちびキャラ風ピクセルスプライトを生成します。
• other — それ以外のすべて: ペット、物体、マスコット、ロゴ、風景。被写体のビーズアート風ピクセルアイコンを生成します。

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

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

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

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

このタスクを実行するためのクレジットが不足しているか、APIキーが無料プランのアカウントに属しています。

入力画像が知的財産 moderation によってフラグ付けされました(Content flagged for intellectual property violation)。知的財産フィルタリングが有効な Enterprise アカウントのみがブロックされ、課金は発生しません。

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

知的財産チェック自体を完了できませんでした(Unable to perform intellectual property check, please try again)。知的財産フィルタリングが有効な Enterprise アカウントは、このチェックで失敗した場合にフェイルクローズします — 課金は発生しませんので、リクエストを再試行してください。

同じOpenAPIエンドポイント経由で作成されたプロトタイプタスクのタスクIDです。プロトタイプは同じMeshyアカウントによって作成され、SUCCEEDEDに到達している必要があります。

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

表示用のオプションのタスク名です。最大100文字です。

各ピースのフットプリントです。使用可能な値:

• square（デフォルト）— 正方形グリッド上の正方形ピース。
• hex — 六角形グリッド上の六角形ピース。六角形ピースは6mmと8mmのみで使用可能です。

ボードの各辺に沿ったピースの数です。使用可能な値: 16または32。32グリッドはより多くのディテールを保持し、16グリッドは同じ被写体に対してより少なく大きなピースになります。

各ピースの辺の長さ（ミリメートル単位）です。使用可能な値: 6、8、または10。grid_sizeと組み合わせることで、印刷されるボードのサイズが決まります——例えば32 × 8 mm ≈ 1辺26 cmになります。10はshape: "hex"では使用できません（斜めの六角形の面はほとんどの一般消費者向けFDMプリンターでオーバーハングになります）。

画像が量子化されるパレットの最大色数です。範囲: [1, 8]。各色はスライサーで1つのフィラメントになります。

各ピースの高さ（ミリメートル単位）です。範囲: [10, 80]。

ビルドによって返される成果物です。使用可能な値:

• 3mf（デフォルト）— model_urls.3mfの下に単一のmodel.3mfを返します。ピースごとに1つのオブジェクトがあり、各オブジェクトにピースの色が付加されています。

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

• パラメータの欠落: input_task_idは必須です。
• 無効なUUID: input_task_idが有効なUUIDではありません。
• 親タスクが未成功: 参照されているプロトタイプタスクがまだSUCCEEDEDに到達していません。
• 候補なし: プロトタイプタスクは成功しましたが、ピクセルアート画像を生成しませんでした。新しいプロトタイプを作成してください。
• オプションが範囲外: optionsのいずれかのフィールドが許可されたセットまたは範囲外です——例えばoptions.grid_size must be 16 or 32、またはoptions.piece_size_mm=10 is not supported for shape=hex; hex pieces are available in 6 and 8 mm。
• サポートされていない形式: output.formatは3mfである必要があります。

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

このタスクを実行するためのクレジットが不足しているか、APIキーが無料プランのアカウントに属しています。

参照されているプロトタイプの画像が知的財産moderationによってフラグ付けされました。知的財産フィルタリングが有効なEnterpriseアカウントのみがブロックされます。料金は請求されません。

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

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

参照されているプロトタイプの知的財産の判定を確立できませんでした（Unable to perform intellectual property check, please try again）。知的財産フィルタリングが有効なEnterpriseアカウントは、このチェックで失敗した場合にフェイルクローズします。料金は請求されません——リクエストを再試行してください。

取得対象の fidget pixel タスクを識別する一意の識別子です。

id が有効なUUIDではありません（Invalid ID）。

タスクの画像が知的財産モデレーションによってフラグ付けされました。知的財産フィルタリングが有効なEnterpriseアカウントのみがブロックされます。

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

知的財産チェックを完了できませんでした（Unable to perform intellectual property check, please try again）。知的財産フィルタリングが有効なEnterpriseアカウントはフェイルクローズ（安全側に倒して失敗）となります。リクエストを再試行してください。

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

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

• 無効な ID：id が有効な UUID ではありません。
• 終了状態：タスクがすでに SUCCEEDED、FAILED、または CANCELED であり、キャンセルできません。

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

ストリーミング対象の fidget pixel タスクを識別する一意のIDです。

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

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

ページサイズの上限。最大許容値は100件です。

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

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

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

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

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

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

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

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

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

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

タスクの結果が失効する時刻のタイムスタンプ（ミリ秒単位）です — タスク終了から3日後です。Enterprise アカウントは API の結果を無期限に保持します（アセット保持期間を参照）。その場合、このタイムスタンプは約100年先に設定されます。

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

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

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

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

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

タスクの一意な識別子。

タスクのタイプ。値はcreative-lab-fidget-pixel-buildです。

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

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

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

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

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

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

タスク結果が失効する時点のタイムスタンプ（ミリ秒単位）— タスク終了の3日後です。エンタープライズアカウントはAPI結果を無期限に保持します（アセット保持期間を参照）。その場合、このタイムスタンプは約100年先に設定されます。

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

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

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

生成されたアセットのダウンロード可能なURLで、フォーマットごとにキー付けされています。ビルドリクエストのoutput.formatで要求されたフォーマットに対応するエントリを1つだけ含みます。タスクがSUCCEEDEDに到達するまでは空です。

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