lowpoly は 2026/10/30 に廃止されます。 リクエストエラーを避けるため、これらの日付までにモデルを切り替えてください。 非推奨の一覧を見る

Creative Lab Collapsible Fidget API

1枚の写真を、折りたたんで平らにし、また伸ばせる、組み立て不要のプリントインプレース型コラプシブルフィジェットトイに、1つのタスクで変換します。被写体のシルエットは入れ子状の同心円リングとなり、折りたためば平らに、伸ばせば元の形に戻ります。このトイは組み立て不要で、1つのパーツとして出力されます。

  • POST /openapi/creative-lab/fidget-collapsible/v1

他のCreative Lab エンドポイントとは異なり、このエンドポイントには独立したprototype（原型）段階とbuild段階がありません。選択すべき候補画像もなく、1つのタスクで写真を3Dモデルに変換します。

リクエストにはジオメトリ設定もありません。ウェブアプリでは、サイズ、レイヤー数、隙間の幅、肉厚、押し出しの深さ、膨らみを設定できますが、APIのタスクはすべて、これらに同じデフォルト値を使用します。

POST/openapi/creative-lab/fidget-collapsible/v1

コラプシブルフィジェットタスクを作成する

写真からコラプシブルフィジェットモデルを生成します。タスクのフィールドについては、コラプシブルフィジェットタスクオブジェクトを参照してください。

タスク1件につき6クレジットかかり、有料プランが必要です。

Request

POST
/openapi/creative-lab/fidget-collapsible/v1
curl https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1 \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>"
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

パラメータ

  • Name
    image_url
    Type
    string
    必須
    Description

    コラプシブルフィジェットに変換する写真。公開URLまたはData URI（data:image/jpeg;base64,<your base64-encoded image data>）として指定します。

    画像はJPG、JPEG、PNG、WebPのいずれかのファイルで、サイズは最大20MBまでです。

    被写体のシルエットがリングになるため、はっきりとした1つの閉じた輪郭を持つ被写体が最適です。背景が複雑だったり、複数の独立した被写体が含まれていたり、非常に細い形状だったりすると、入れ子になった壁を作るための十分な領域が残らないことがあります。その場合、タスクは失敗します。

  • Name
    name
    Type
    string
    Description

    タスクの名前で、最大100文字まで指定できます。タスクのnameフィールドに返されますが、Meshyはこれをモデルに刻印しません。名前が長すぎると400が返されます。

戻り値

resultフィールドには新しいタスクのIDが入ります。statusがSUCCEEDEDになるまでタスクを取得するか、ストリーミングしてください。その後、model_urls.stlから印刷可能なSTLファイルをダウンロードします。先にモデルをプレビューしたい場合は、model_urls.glbが存在するときにそこからGLBファイルをダウンロードしてください。

失敗モード

  • Name
    400 - Bad Request
    Description

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

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

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

  • Name
    401 - Unauthorized
    Description

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

  • Name
    402 - Payment Required
    Description

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

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

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

  • Name
    403 - Forbidden
    Description

    チームでIPフィルタリングが有効になっており、Meshyがその画像を第三者の知的財産として検知しました。利用権を持つ画像を送信してください。

  • Name
    429 - Too Many Requests
    Description

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

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

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

GET/openapi/creative-lab/fidget-collapsible/v1/:id

Collapsible Fidgetタスクを取得

Collapsible Fidgetタスクを返します。このエンドポイントで作成されたタスクのみが返されます。他のCreative Labエンドポイントで作成されたタスク、またはウェブアプリで作成されたタスクの場合は 404 が返ります。

フィールドについては、Collapsible Fidgetタスクオブジェクトを参照してください。

Request

GET
/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578
curl https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}

パラメータ

  • Name
    id
    Type
    path
    Description

    作成レスポンスからのタスクIDです。

戻り値

Collapsible Fidgetタスクオブジェクト。

失敗モード

  • Name
    400 - Bad Request
    Description

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

  • Name
    403 - Forbidden
    Description

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

  • Name
    404 - Not Found
    Description

    このIDのCollapsible Fidgetタスクがあなたのアカウントに属していないか、このエンドポイントで作成されたものではありません。IDを確認してください。

  • Name
    500 - Internal Server Error
    Description

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

DELETE/openapi/creative-lab/fidget-collapsible/v1/:id

Collapsible Fidgetタスクを削除する

Collapsible Fidgetタスクをキャンセルします。PENDING状態のタスクをキャンセルすると、クレジットが返金されます。IN_PROGRESS状態のタスクは、すでにワーカーが処理を開始しているため、返金なしでキャンセルされます。最終状態（SUCCEEDED、FAILED、またはCANCELED）のタスクはキャンセルできません。

Request

DELETE
/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578
curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 204 No Content on success (empty body).

パスパラメータ

  • Name
    id
    Type
    path
    Description

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

戻り値

空の本文を伴う204 No Content。

失敗モード

  • Name
    400 - Bad Request
    Description

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

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

    このIDを持つCollapsible Fidgetタスクがお客様のアカウントに存在しないか、このエンドポイントで作成されたタスクではありません。IDを確認してください。

GET/openapi/creative-lab/fidget-collapsible/v1/:id/stream

折りたたみ式フィジェットタスクをストリーミングする

折りたたみ式フィジェットタスクの更新をサーバー送信イベント（SSE）としてストリーミングします。タスクが存在しない場合、またはこのエンドポイントで作成されたものではない場合、ストリームは status_code: 404 を持つ error イベントを1件送信してクローズします。

Request

GET
/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578/stream
curl -N https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example (task not found, or not created through this endpoint)
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// Every frame is the full task object; fields not yet populated are null / empty.
// The following PENDING frame is shortened to the fields that change.
event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}

パラメータ

  • Name
    id
    Type
    path
    Description

    作成レスポンスから得られるタスクID。

返り値

折りたたみ式フィジェットタスクオブジェクトのストリーム。各イベントには、折りたたみ式フィジェットタスクを取得するが返すのと同じ、完全なタスクオブジェクトが含まれます。タスクが PENDING または IN_PROGRESS の間は、出力フィールドはまだ空（null、[]、または {}）であり、finished_at は null です。

IPフィルタリングがタスクの結果をブロックした場合、ストリームはその代わりに、get リクエストが返すであろう status_code を持つ error イベントを1件送信します。

GET/openapi/creative-lab/fidget-collapsible/v1

Collapsible Fidget タスク一覧を取得

お使いの Collapsible Fidget タスクを、1 ページずつ返します。このエンドポイントで作成されたタスクのみが含まれます。

Request

GET
/openapi/creative-lab/fidget-collapsible/v1
curl https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "creative-lab-fidget-collapsible",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1729123456000,
    "started_at": 1729123460000,
    "finished_at": 1729123512000,
    "expires_at": 1729382712000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
    }
  }
]

クエリパラメータ

  • Name
    page_num
    Type
    integer
    デフォルト 1
    Description

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

  • Name
    page_size
    Type
    integer
    デフォルト 10
    Description

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

  • Name
    sort_by
    Type
    string
    デフォルト -created_at
    Description

    並び順。

    指定可能な値:

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

返り値

Collapsible Fidget タスクオブジェクトの配列。

Collapsible Fidget タスクオブジェクト

Collapsible Fidget タスクは、写真を印刷してそのまま使える折りたたみ式フィジェットモデルに変換します。これは単一ステージのタスクであるため、そこから連鎖するプロトタイプタスクはありません。レスポンスには、Meshy が過程で作成するシルエットは含まれません。

プロパティ

Example Collapsible Fidget Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}
  • Name
    id
    Type
    string
    Description

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

  • Name
    type
    Type
    string
    Description

    タスクタイプ。常に creative-lab-fidget-collapsible です。

  • Name
    name
    Type
    string
    Description

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

  • Name
    status
    Type
    string
    Description

    タスクのステータス。

    使用可能な値：

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

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

  • Name
    created_at
    Type
    timestamp
    Description

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

  • Name
    started_at
    Type
    timestamp
    Description

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

  • Name
    finished_at
    Type
    timestamp
    Description

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

  • Name
    expires_at
    Type
    timestamp
    Description

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

  • Name
    preceding_tasks
    Type
    integer
    Description

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

  • Name
    task_error
    Type
    object
    Description

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

  • Name
    consumed_credits
    Type
    integer
    Description

    タスクに対して返金後に課金されたクレジット数。エラーを返したリクエストには課金されません。失敗したタスクは Meshy が返金するため 0 になります。キャンセルは、タスクが PENDING の間のみタスクを返金します。Meshy が課金内容を読み取れない場合、get またはストリームのレスポンスにはこのフィールドが含まれず、リストリクエストは 500 を返します。その場合は、リクエストを再試行してください。

  • Name
    model_urls
    Type
    object
    Description

    3Dモデルのダウンロード URL。タスクが成功するまでは空です。成功したタスクには常に stl があり、Meshy がプレビューをレンダリングした場合のみ glb があります。

    • Name
      stl
      Type
      string
      Description

      印刷に使用するファイルである STL ファイルのダウンロード URL。スライサーで直接開くことができます。

    • Name
      glb
      Type
      string
      Description

      3Dビューアでモデルをプレビューするための GLB ファイルのダウンロード URL。その色はプレビュー用のみです。STL ファイルには色がないため、印刷されたフィジェットの色はフィラメントの色になります。

      Meshy がプレビューをレンダリングできない場合、model_urls に glb キーは含まれないため、読み取る前にキーの存在を確認してください。SUCCEEDED タスクには常に stl があります。