変換API

変換APIを使用すると、既存の3Dモデルを別のファイル形式に変換できます。

POST/openapi/v1/convert

変換タスクを作成

この endpoint は新しいフォーマット変換タスクを作成します。

パラメータ

input_task_id または model_url のいずれか一方のみが 必須 です。両方が指定された場合、input_task_id が優先されます。

  • Name
    input_task_id
    Type
    string
    必須
    Description

    変換したいモデルを含む、完了済みの Meshy タスクの ID。 タスクのステータスは SUCCEEDED である必要があります。

  • Name
    model_url
    Type
    string
    必須
    Description

    3D モデルファイルを指す、公開アクセス可能な URL またはデータ URI。 対応フォーマット: .glb, .gltf, .obj, .fbx, .stl。 データ URI の場合は、MIME タイプ application/octet-stream を使用してください。

  • Name
    target_formats
    Type
    string[]
    必須
    Description

    変換後モデルの出力フォーマットのリスト。 利用可能な値: glb, fbx, obj, usdz, blend, stl, 3mf。

戻り値

レスポンスの result プロパティには、新しく作成された変換タスクの id が含まれます。

失敗モード

  • 400 - Bad Request

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

  • パラメータ不足: model_url または input_task_id のいずれかを指定する必要があります。
  • target_formats の不足: 少なくとも 1 つのターゲットフォーマットを指定する必要があります。
  • 無効な入力タスク: input_task_id は成功したタスクを参照している必要があります。
  • 無効なモデルフォーマット: model_url が未対応の拡張子を持つファイルを指しています。
  • 到達不能な URL: model_url をダウンロードできませんでした。
  • 401 - Unauthorized

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

  • 402 - Payment Required

このタスクを実行するためのクレジットが不足しています。

  • 429 - Too Many Requests

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

Request

POST
/openapi/v1/convert
curl https://api.meshy.ai/openapi/v1/convert \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "target_formats": ["fbx", "stl"]
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}
GET/openapi/v1/convert/:id

変換タスクを取得する

この endpoint は、ID によって変換タスクを取得します。

パラメータ

  • Name
    id
    Type
    path
    Description

    取得する変換タスクの ID。

戻り値

Convert Task オブジェクト。

Request

GET
/openapi/v1/convert/:id
curl https://api.meshy.ai/openapi/v1/convert/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "convert",
  "model_urls": {
      "glb": "",
      "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
      "obj": "",
      "usdz": "",
      "stl": "https://assets.meshy.ai/.../model.stl?Expires=..."
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
  "consumed_credits": 1
}
DELETE/openapi/v1/convert/:id

Convertタスクを削除

このendpointは、関連するすべてのモデルとデータを含め、convertタスクを完全に削除します。この操作は元に戻せません。

パスパラメータ

  • Name
    id
    Type
    path
    Description

    削除するconvertタスクのID。

戻り値

成功時に 200 OK を返します。

Request

DELETE
/openapi/v1/convert/:id
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/convert/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 200 Ok on success.
GET/openapi/v1/convert

変換タスクの一覧表示

この endpoint では、変換タスクの一覧を取得できます。

パラメーター

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

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

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

    ページサイズの上限。許可される最大値は 50 件です。

  • Name
    sort_by
    Type
    string
    Description

    ソート対象のフィールド。 利用可能な値:

    • +created_at: 作成時刻の昇順でソートします。
    • -created_at: 作成時刻の降順でソートします。

戻り値

変換タスクオブジェクト のページネーションされた一覧を返します。

Request

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

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "convert",
    "model_urls": {
      "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
      "stl": "https://assets.meshy.ai/.../model.stl?Expires=..."
    },
    "progress": 100,
    "status": "SUCCEEDED",
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "task_error": null,
    "consumed_credits": 1
  }
]
GET/openapi/v1/convert/:id/stream

変換タスクをストリームする

この endpoint は、Server-Sent Events (SSE) を使用して変換タスクのリアルタイム更新をストリームします。

パラメータ

  • Name
    id
    Type
    path
    Description

    ストリームする変換タスクの一意の識別子。

戻り値

Server-Sent Events として 変換タスクオブジェクト のストリームを返します。

PENDING または IN_PROGRESS のタスクでは、レスポンスストリームには必要な progress および status フィールドのみが含まれます。

Request

GET
/openapi/v1/convert/:id/stream
curl -N https://api.meshy.ai/openapi/v1/convert/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Message event examples illustrate task progress.
event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "convert",
  "model_urls": {
    "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
    "stl": "https://assets.meshy.ai/.../model.stl?Expires=..."
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
  "consumed_credits": 1
}

変換タスクオブジェクト

変換タスクオブジェクトは、形式変換ジョブを表します。

プロパティ

  • id · string

タスクの一意の識別子。

  • type · string

タスクの種類。値は convert です。

  • model_urls · object

変換されたモデルファイルのダウンロード可能なURL。target_formats で指定された形式のみURLが含まれます。その他の形式のプロパティは空文字列になります。

  • progress · integer

タスクの進捗状況（0-100）。

  • status · string

タスクのステータス。指定可能な値: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED。

  • preceding_tasks · integer

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

  • created_at · timestamp

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

  • started_at · timestamp

タスクが開始された日時のタイムスタンプ（ミリ秒）。開始されていない場合は 0。

  • finished_at · timestamp

タスクが完了した日時のタイムスタンプ（ミリ秒）。完了していない場合は 0。

  • task_error · object

タスクが失敗した場合のエラーオブジェクト。詳細については Errors を参照してください。

  • consumed_credits · integer

このタスクで消費されたクレジット数（変換タスクごとに1クレジット）。FAILED タスクの場合は 0 を返します。