変換API

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

POST/openapi/v1/convert

変換タスクを作成する

このエンドポイントは新しいフォーマット変換タスクを作成します。

パラメータ

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

  • Name
    input_task_id
    Type
    string
    必須
    Description

    変換したいモデルを持つ完了したMeshyタスクのIDです。 タスクは SUCCEEDED のステータスでなければなりません。

  • Name
    model_url
    Type
    string
    必須
    Description

    公開アクセス可能なURLまたは3Dモデルファイルを指すData URIです。 サポートされているフォーマット: .glb, .gltf, .obj, .fbx, .stl。 Data 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キーを確認してください。

  • 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

変換タスクを取得する

このエンドポイントは、IDによって変換タスクを取得します。

パラメータ

  • Name
    id
    Type
    path
    Description

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

戻り値

変換タスクオブジェクト。

リクエスト

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

レスポンス

{
  "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

変換タスクを削除する

このエンドポイントは、関連するすべてのモデルとデータを含む変換タスクを永久に削除します。この操作は元に戻せません。

パスパラメータ

  • Name
    id
    Type
    path
    Description

    削除する変換タスクの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

変換タスクのリスト

このエンドポイントを使用すると、変換タスクのリストを取得できます。

パラメータ

  • 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

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

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

パラメータ

  • Name
    id
    Type
    path
    Description

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

戻り値

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

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

リクエスト

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

レスポンスストリーム

// 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

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

  • consumed_credits · integer

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