Creative Lab — 折りたたみ式フィジェット API

元となる写真を、その場でプリント可能な折りたたみ式フィジェットトイに変換します。被写体のシルエットが入れ子状の同心リングの集合となり、平らに折りたたんだり再び伸ばしたりでき、組み立て不要の一体成形でプリントされます。

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

他の Creative Lab の endpoint とは異なり、これにはプロトタイプ／ビルド段階のペアがありません——選択すべき中間候補が存在しないため、1つのタスクが画像を3Dモデルまで一貫して処理します。ウェブアプリが公開しているジオメトリの制御項目（サイズ、レイヤー数、隙間の幅、肉厚、押し出しの深さ、膨らみ）もリクエストには含まれません。すべてのタスクは同じサーバー側のデフォルト値でビルドされます。

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

折り畳み式フィジェットタスクの作成

元となる写真から折り畳み式フィジェットモデルを生成します。レスポンスの形式については The Collapsible Fidget Task Object を参照してください。

タスク1件あたり6クレジットを消費し、有料プランが必要です。

パラメータ

  • Name
    image_url
    Type
    string
    必須
    Description

    Meshyが折り畳み式フィジェットに変換する元となる写真です。現在サポートしている形式は.jpg、.jpeg、.png、.webpです。

    画像を提供する方法は2種類あります。

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

    1つの明確で閉じた輪郭を持つ被写体が最適です。シルエットがそのままリングになります。背景が煩雑だったり、複数の別々の被写体があったり、非常に薄い形状の場合、入れ子状の壁に必要な面積が不足し、タスクエラーで失敗します。

  • Name
    name
    Type
    string
    Description

    表示用の任意のタスク名です。最大100文字。これはタスクのラベルとしてのみ使用され、モデルに刻印されるわけではありません。

返り値

レスポンスのresultプロパティには、新しく作成された折り畳み式フィジェットタスクのタスクidが含まれます。Get a Taskエンドポイントをポーリングするか、streamをサブスクライブして、タスクがSUCCEEDEDに達するまで待機し、その後model_urls.stlから印刷可能なSTLをダウンロードしてください(存在する場合は、model_urls.glbからGLBをダウンロードして先にプレビューすることもできます)。

失敗モード

  • Name
    400 - Bad Request
    Description

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

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

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

  • Name
    402 - Payment Required
    Description

    アカウントが無料プランである(このエンドポイントでのタスク作成には有料プランが必要です)か、クレジットが不足しています。

  • Name
    403 - Forbidden
    Description

    入力画像が知的財産権侵害としてフラグ付けされました。

  • Name
    429 - Too Many Requests
    Description

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

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"
}
GET/openapi/creative-lab/fidget-collapsible/v1/:id

折りたたみ式フィジェットタスクを取得する

有効なタスク id を指定して、折りたたみ式フィジェットタスクを取得します。このエンドポイントで作成されたタスクのみがここで取得可能です。別の Creative Lab エンドポイントで作成されたタスクや、ウェブアプリで作成されたタスクの場合は 404 が返されます。

レスポンスの形式については、折りたたみ式フィジェットタスクオブジェクトを参照してください。

パラメータ

  • Name
    id
    Type
    path
    Description

    取得する折りたたみ式フィジェットタスクの一意の識別子です。

戻り値

レスポンスには折りたたみ式フィジェットタスクオブジェクトが含まれます。

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=***"
  }
}
DELETE/openapi/creative-lab/fidget-collapsible/v1/:id

Delete a Collapsible Fidget Task

折りたたみ式フィジェットタスクをキャンセルします。タスクがまだ PENDING の場合、作成時に消費されたクレジットは返金されます。すでに IN_PROGRESS のタスクは返金なしでキャンセルされます（ワーカーがすでにリソースを消費している可能性があるため）。すでに終了状態 （SUCCEEDED、FAILED、CANCELED）に達しているタスクはキャンセルできません。

パスパラメータ

  • Name
    id
    Type
    path
    Description

    キャンセルする折りたたみ式フィジェットタスクの一意の識別子。

戻り値

成功時には空のボディとともに 204 No Content を返します。

失敗モード

  • Name
    400 - Bad Request
    Description

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

  • Name
    404 - Not Found
    Description

    タスクが存在しないか、別のユーザーに属しているか、このエンドポイントを通じて作成されたものではありません。

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).
GET/openapi/creative-lab/fidget-collapsible/v1/:id/stream

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

Server-Sent Events (SSE) を介して、折りたたみ可能なフィジェットタスクのリアルタイム更新をストリーミングします。存在しないタスク、またはこのエンドポイントを通じて作成されなかったタスクの場合、status_code: 404 を伴う単一の event: error ペイロードが発行され、ストリームは閉じられます。

パラメーター

  • Name
    id
    Type
    path
    Description

    ストリーミングする折りたたみ可能なフィジェットタスクの一意の識別子。

戻り値

Collapsible Fidget タスクオブジェクトのストリームを Server-Sent Events として返します。各フレームには、そのステージにおけるタスクオブジェクト全体が含まれます — これは Get エンドポイントが返すものと同じ形式です — そのため、タスクが PENDING または IN_PROGRESS の間は、出力フィールドはまだ値が入っておらず（null、[] または {}）、finished_at は null です。

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 PENDING frame below is abbreviated 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=***"
  }
}
GET/openapi/creative-lab/fidget-collapsible/v1

List Collapsible Fidget Tasks

折りたたみ式フィジェットタスクのページネーションされたリストを取得します。このエンドポイントを通じて作成されたタスクのみが含まれます。

クエリパラメータ

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

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

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

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

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

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

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

戻り値

折りたたみ式フィジェットタスクオブジェクトのページネーションされたリストを返します。

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=***"
    }
  }
]

The Collapsible Fidget Task Object

The Collapsible Fidget Task オブジェクトは、Meshy が管理するワークユニットであり、元となる写真をプリントするだけで組み立て不要な折りたたみ式フィジェットモデルに変換します。これは単一ステージのタスクです。つまり、連鎖元となるプロトタイプは存在せず、中間シルエットもレスポンスには含まれません。

Properties

  • Name
    id
    Type
    string
    Description

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

  • Name
    type
    Type
    string
    Description

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

  • Name
    name
    Type
    string
    Description

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

  • Name
    status
    Type
    string
    Description

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

  • Name
    progress
    Type
    integer
    Description

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

  • Name
    created_at
    Type
    timestamp
    Description

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

    タイムスタンプは、RFC 3339 規格に従い、 1970年1月1日 UTC からの経過ミリ秒数を表します。 例えば、2023年9月1日（金曜日）12:00:00 PM GMT は 1693569600000 と表されます。これは Meshy API のすべてのタイムスタンプに当てはまります。

  • Name
    started_at
    Type
    timestamp
    Description

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

  • Name
    finished_at
    Type
    timestamp
    Description

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

  • Name
    expires_at
    Type
    timestamp
    Description

    タスクの結果が期限切れになる時刻を示すタイムスタンプ（ミリ秒単位）です。

  • Name
    preceding_tasks
    Type
    integer
    Description

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

    このフィールドの値は、タスクのステータスが PENDING の場合にのみ意味を持ちます。

  • Name
    task_error
    Type
    object
    Description

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

  • Name
    consumed_credits
    Type
    integer
    Description

    このタスクによって消費されたクレジットの数です。タスクのステータスが PENDING、IN_PROGRESS、または SUCCEEDED の場合に存在します。FAILED タスクの場合は 0 が返されます（失敗時はクレジットが返還されます）。

  • Name
    model_urls
    Type
    object
    Description

    生成された 3D モデルのダウンロード可能な URL です。タスクが SUCCEEDED になると値が設定されます。stl は常に存在し、glb はプレビューレンダリングが成功した場合にのみ存在します。

    • Name
      stl
      Type
      string
      Description

      STL ファイルのダウンロード可能な URL です。これは印刷可能な成果物であり、そのままスライサーに送ることができます。

    • Name
      glb
      Type
      string
      Description

      3D ビューアでモデルをプレビューするための GLB ファイルのダウンロード可能な URL です。その色はプレビュー専用であり、STL には色情報が含まれず、印刷されたフィジェットの色はフィラメントの色によって決まります。GLB はベストエフォートで提供されます。プレビューレンダリングが利用できない場合、このキーは model_urls から完全に省略されるため、防御的に読み取ってください。stl が成果物であり、SUCCEEDED タスクには常に存在します。

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=***"
  }
}