> ## Documentation Index
> Fetch the complete documentation index at: https://docs.comfy.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Meshy 7.1 を Comfy Router で使用する

> Comfy Router 経由で meshy/meshy-7.1 を呼び出します: エンドポイント、リクエストの形状、Router が返すレスポンスについて説明します。

Comfy Router が Meshy から提供する `meshy/meshy-7.1` の API リファレンス。

## クイックスタート

[ご自身の Comfy ワークスペース](https://platform.comfy.org/profile/api-keys?onboarding=router)でキーを作成し、`COMFY_API_KEY` としてエクスポートします。Python、TypeScript、Swift のスニペットは Comfy SDK（`pip install comfy-sdk`、`npm install @comfyorg/sdk`、および [`ComfySwiftSDK`](https://github.com/Comfy-Org/comfy-swift-sdk) Swift パッケージ）を使用しています。cURL のスニペットは、同じ呼び出しを生の HTTP で行うものです。

**モデル ID:** `meshy/meshy-7.1`

**エンドポイント:** `POST https://api.comfy.org/v2/models/meshy/meshy-7.1`

<Tabs>
  <Tab title="結果を待つ">
    <CodeGroup>
      ```python Python theme={null}
      from comfy_sdk import Comfy

      # 環境変数から COMFY_API_KEY を読み取ります。
      # SDK は自動的に冪等キーを作成し、自動リトライのために再利用します。
      with Comfy() as client:
          result = client.models.run(
              "meshy/meshy-7.1",
              {
                  "art_style": "realistic",
                  "mode": "preview",
                  "prompt": "a red cube",
              },
          )

      print(result)
      ```

      ```typescript TypeScript theme={null}
      import { comfy } from "@comfyorg/sdk";

      // 環境変数から COMFY_API_KEY を読み取ります。
      // SDK は自動的に冪等キーを作成し、自動リトライのために再利用します。
      const { data } = await comfy.models.run("meshy/meshy-7.1", {
        art_style: "realistic",
        mode: "preview",
        prompt: "a red cube",
      });

      console.log(data);
      ```

      ```swift Swift theme={null}
      import Foundation
      import ComfySwiftSDK

      // 環境変数から COMFY_API_KEY を読み取ります。
      // SDK は呼び出しごとに冪等キーを生成し、自動リトライのために再利用します。
      let client = ComfyCloudClient(apiKey: ProcessInfo.processInfo.environment["COMFY_API_KEY"]!)
      let result = try await client.models.run(
          "meshy/meshy-7.1",
          input: [
              "art_style": "realistic",
              "mode": "preview",
              "prompt": "a red cube",
          ]
      )

      print(result.output)
      ```

      ```bash cURL theme={null}
      curl https://api.comfy.org/v2/models/meshy/meshy-7.1 \
        -H "X-API-Key: $COMFY_API_KEY" \
        -H "Idempotency-Key: $(uuidgen)" \
        -H "Content-Type: application/json" \
        -d "{\"art_style\": \"realistic\", \"mode\": \"preview\", \"prompt\": \"a red cube\"}"
      ```
    </CodeGroup>
  </Tab>

  <Tab title="キューに送信して後で収集する">
    同じボディを `POST https://api.comfy.org/v2/models/meshy/meshy-7.1/requests` に送信します。Router は実行が受け付けられるとすぐに `201` と `request_id` を返し、結果は準備でき次第、このプロセスまたは別のプロセスから収集されます。[キュー配信](/ja/development/comfy-router/queue)では、ステータス、キャンセル、収集について説明します。

    <CodeGroup>
      ```python Python theme={null}
      from comfy_sdk import Comfy

      # 環境変数から COMFY_API_KEY を読み取ります。
      # 各 submit() 呼び出しは独自の Idempotency-Key を生成し、自動リトライのために再利用します。
      with Comfy() as client:
          handle = client.models.submit(
              "meshy/meshy-7.1",
              {
                  "art_style": "realistic",
                  "mode": "preview",
                  "prompt": "a red cube",
              },
          )
          print("request_id:", handle.request_id)  # モデル ID と合わせて、別のプロセスに必要な情報はこれだけです

          # リクエストが完了するまでポーリングし、サーバーが指定する Retry-After の時間待機します。
          for update in handle.iter_events():
              print(update.status, update.queue_position)

          # プロバイダー自身のペイロードであり、models.run() が返すのと同じ値です。
          # 失敗したリクエストまたはキャンセル済みのリクエストは、ここで型付きの Router エラーを発生させます。
          result = handle.get()

      print(result)
      ```

      ```typescript TypeScript theme={null}
      import { comfy } from "@comfyorg/sdk";

      // 環境変数から COMFY_API_KEY を読み取ります。
      // 各 submit() 呼び出しは独自の Idempotency-Key を生成し、自動リトライのために再利用します。
      const handle = await comfy.models.submit("meshy/meshy-7.1", {
        art_style: "realistic",
        mode: "preview",
        prompt: "a red cube",
      });
      console.log("requestId:", handle.requestId); // モデル ID と合わせて、別のプロセスに必要な情報はこれだけです

      // リクエストが完了するまでポーリングし、サーバーが指定する Retry-After の時間待機します。
      for await (const update of handle.events()) {
        console.log(update.status, update.queuePosition);
      }

      // models.run() が返すのと同じ結果です。失敗したリクエストまたはキャンセル済みのリクエストは、ここで reject されます。
      const result = await handle.get();

      console.log(result.data);
      ```

      ```swift Swift theme={null}
      import Foundation
      import ComfySwiftSDK

      // 環境変数から COMFY_API_KEY を読み取ります。
      // 各 submit() 呼び出しは独自の Idempotency-Key を生成し、自動リトライのために再利用します。
      let client = ComfyCloudClient(apiKey: ProcessInfo.processInfo.environment["COMFY_API_KEY"]!)
      let handle = try await client.models.submit(
          "meshy/meshy-7.1",
          input: [
              "art_style": "realistic",
              "mode": "preview",
              "prompt": "a red cube",
          ]
      )
      print("requestId:", handle.requestId)  // モデル ID と合わせて、別のプロセスに必要な情報はこれだけです

      // リクエストが完了するまでポーリングし、サーバーが指定する Retry-After の時間待機します。
      for try await update in handle.events() {
          print(update.state.rawValue, update.queuePosition.map(String.init) ?? "unknown")
      }

      // プロバイダー自身のペイロードであり、models.run() が返すのと同じ値です。
      // 失敗したリクエストまたはキャンセル済みのリクエストは、ここで型付きの Router エラーをスローします。
      let result = try await handle.result()

      print(result.output)
      ```

      ```bash cURL theme={null}
      # 1. 送信します。Router は 201 と request_id、status_url、response_url、cancel_url を返します。
      curl https://api.comfy.org/v2/models/meshy/meshy-7.1/requests \
        -H "X-API-Key: $COMFY_API_KEY" \
        -H "Idempotency-Key: $(uuidgen)" \
        -H "Content-Type: application/json" \
        -d "{\"art_style\": \"realistic\", \"mode\": \"preview\", \"prompt\": \"a red cube\"}"

      # 2. ステータスが COMPLETED になるまでポーリングし、各レスポンスが指定する Retry-After 秒待機します。
      REQUEST_ID="<request_id from the 201 body>"
      curl -i https://api.comfy.org/v2/models/meshy/meshy-7.1/requests/$REQUEST_ID/status \
        -H "X-API-Key: $COMFY_API_KEY"

      # 3. 収集します。200 はモデルのネイティブ出力、202 はまだ実行中のステータスボディを返します。
      curl https://api.comfy.org/v2/models/meshy/meshy-7.1/requests/$REQUEST_ID \
        -H "X-API-Key: $COMFY_API_KEY"
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## スキーマ

### 入力

#### `preview` バリアント

<ParamField body="ai_model" type="string">
  実行するMeshyモデル。Comfy Routerルートではこれはパス（`/v2/models/meshy/{model}`）から提供され、省略するか null として送信できます。Routerは検証後にパスのモデルをここに書き込みます。v1 /proxyルートではMeshyTextTo3DPreviewRequestを参照してください。これはこれをMeshyAiModelに制約します。
</ParamField>

<ParamField body="art_style" type="string" default="&#x22;realistic&#x22;">
  オブジェクトの希望するアートスタイルを記述します。

  指定可能な値: `realistic`、`sculpture`
</ParamField>

<ParamField body="geometry_resolution" type="string" default="&#x22;standard&#x22;">
  生成されるメッシュのジオメトリ解像度。2kと4kは、より細かい表面ディテールのためにUltraパスを実行します。2kには ai\_model meshy-7、meshy-7.1 または latest が必要です。4kには meshy-7.1 または latest が必要です。

  指定可能な値: `standard`、`2k`、`4k`
</ParamField>

<ParamField body="is_a_t_pose" type="boolean" default="false">
  非推奨。代わりに pose\_mode を使用してください。モデルをA/Tポーズで生成するかどうか。
</ParamField>

<ParamField body="mode" type="string" required>
  プレビュータスクを作成する場合、このフィールドは "preview" に設定する必要があります。

  指定可能な値: `preview`
</ParamField>

<ParamField body="moderation" type="boolean" default="false">
  true の場合、入力コンテンツは有害な可能性のあるコンテンツがないかスクリーニングされます。
</ParamField>

<ParamField body="pose_mode" type="string">
  生成されるモデルのポーズモードを指定します。

  指定可能な値: `a-pose`、`t-pose`、\`\`
</ParamField>

<ParamField body="prompt" type="string" required>
  3Dモデルがどのようなオブジェクトであるかを記述します。最大600文字。
</ParamField>

<ParamField body="should_remesh" type="boolean" default="true">
  リメッシュフェーズを有効にするかどうかを制御します。false の場合、最も高精度な三角形メッシュを返します。
</ParamField>

<ParamField body="symmetry_mode" type="string" default="&#x22;auto&#x22;">
  モデル生成中の対称性の動作を制御します。

  指定可能な値: `off`、`auto`、`on`
</ParamField>

<ParamField body="target_polycount" type="integer" default="30000">
  生成されるモデルのポリゴンの目標数を指定します。有効範囲は100～300,000です。

  範囲: `100` ～ `300000`
</ParamField>

<ParamField body="topology" type="string" default="&#x22;triangle&#x22;">
  生成されるモデルのトポロジーを指定します。

  指定可能な値: `quad`、`triangle`
</ParamField>

<ParamField body="ultra_mode" type="boolean" default="false">
  非推奨。代わりに geometry\_resolution を使用してください。true は geometry\_resolution 2k と同等です。ai\_model が meshy-7、meshy-7.1 または latest の場合にのみサポートされます。
</ParamField>

#### `refine` バリアント

<ParamField body="ai_model" type="string">
  実行するMeshyモデル。Comfy Routerルートではこれはパス（`/v2/models/meshy/{model}`）から提供され、省略するか null として送信できます。Routerは検証後にパスのモデルをここに書き込みます。v1 /proxyルートではMeshyTextTo3DRefineRequestを参照してください。これはこれをMeshyAiModelに制約します。
</ParamField>

<ParamField body="enable_pbr" type="boolean" default="false">
  ベースカラーに加えてPBRマップ（metallic、roughness、normal）を生成します。Sculptureスタイルを使用する場合は enable\_pbr を false に設定する必要があることに注意してください。
</ParamField>

<ParamField body="mode" type="string" required>
  リファインタスクを作成する場合、このフィールドは "refine" に設定する必要があります。

  指定可能な値: `refine`
</ParamField>

<ParamField body="moderation" type="boolean" default="false">
  true の場合、入力コンテンツは有害な可能性のあるコンテンツがないかスクリーニングされます。
</ParamField>

<ParamField body="preview_task_id" type="string" required>
  対応するプレビュータスクID。指定したプレビュータスクのステータスは SUCCEEDED である必要があります。
</ParamField>

<ParamField body="texture_image_url" type="string">
  テクスチャリング処理をガイドする2D画像を提供します。.jpg、.jpeg、.png 形式、または base64 エンコードされたデータURIをサポートします。
</ParamField>

<ParamField body="texture_prompt" type="string">
  テクスチャリング処理をガイドする追加のテキストプロンプトを提供します。最大600文字。
</ParamField>

<ParamField body="texture_resolution" type="string" default="&#x22;2k&#x22;">
  生成されるテクスチャのテクスチャ解像度。2k、4k、8k のいずれかです。4k と 8k には ai\_model meshy-6、meshy-7、meshy-7.1 または latest が必要です。

  指定可能な値: `2k`、`4k`、`8k`
</ParamField>

`GET /v2/models/meshy/meshy-7.1/openapi.json` で Router が提供するスキーマから生成されています。これは、リクエストがプロバイダーに到達する前に Router が呼び出しを検証する対象となる、同じドキュメントです。

### 出力

<ResponseField name="art_style" type="string">
  プレビュータスクの作成に使用された、変更されていないart\_style。
</ResponseField>

<ResponseField name="created_at" type="integer">
  タスクが作成されたときのタイムスタンプ（ミリ秒単位）。

  形式: `int64`
</ResponseField>

<ResponseField name="finished_at" type="integer">
  タスクが完了したときのタイムスタンプ（ミリ秒単位）。完了していない場合は0。

  形式: `int64`
</ResponseField>

<ResponseField name="id" type="string" required>
  タスクの一意の識別子。
</ResponseField>

<ResponseField name="model_urls" type="object">
  Meshyによって生成されたテクスチャ付き3DモデルファイルをダウンロードできるURL。
</ResponseField>

<ResponseField name="model_urls.fbx" type="string">
  FBXファイルをダウンロードできるURL。
</ResponseField>

<ResponseField name="model_urls.glb" type="string">
  GLBファイルをダウンロードできるURL。
</ResponseField>

<ResponseField name="model_urls.mtl" type="string">
  MTLファイルをダウンロードできるURL。
</ResponseField>

<ResponseField name="model_urls.obj" type="string">
  OBJファイルをダウンロードできるURL。
</ResponseField>

<ResponseField name="model_urls.usdz" type="string">
  USDZファイルをダウンロードできるURL。
</ResponseField>

<ResponseField name="negative_prompt" type="string">
  後方互換性のために維持されている非推奨のフィールド。
</ResponseField>

<ResponseField name="preceding_tasks" type="integer">
  先行するタスクの数。statusがPENDINGの場合にのみ意味を持ちます。
</ResponseField>

<ResponseField name="progress" type="integer">
  タスクの進捗。開始されていない場合は0、成功した場合は100。

  範囲: `0` から `100`
</ResponseField>

<ResponseField name="prompt" type="string">
  タスクの作成に使用された、変更されていないプロンプト。
</ResponseField>

<ResponseField name="started_at" type="integer">
  タスクが開始されたときのタイムスタンプ（ミリ秒単位）。開始されていない場合は0。

  形式: `int64`
</ResponseField>

<ResponseField name="status" type="string" required>
  可能な値: `SUCCEEDED`
</ResponseField>

<ResponseField name="task_error" type="object">
  タスクが失敗した場合にエラーメッセージを含むエラーオブジェクト。
</ResponseField>

<ResponseField name="task_error.message" type="string">
  詳細なエラーメッセージ。
</ResponseField>

<ResponseField name="texture_image_url" type="string">
  テクスチャリングプロセスをガイドするために使用されたテクスチャ画像をダウンロードできるURL。
</ResponseField>

<ResponseField name="texture_prompt" type="string">
  リファイン段階でテクスチャリングプロセスをガイドするために提供される追加のテキストプロンプト。
</ResponseField>

<ResponseField name="texture_richness" type="string">
  後方互換性のために維持されている非推奨のフィールド。
</ResponseField>

<ResponseField name="texture_urls" type="object[]">
  タスクから生成されるテクスチャURLオブジェクトの配列。
</ResponseField>

<ResponseField name="texture_urls[].base_color" type="string">
  ベースカラーマップ画像をダウンロードできるURL。
</ResponseField>

<ResponseField name="texture_urls[].metallic" type="string">
  メタリックマップ画像をダウンロードできるURL。
</ResponseField>

<ResponseField name="texture_urls[].normal" type="string">
  ノーマルマップ画像をダウンロードできるURL。
</ResponseField>

<ResponseField name="texture_urls[].roughness" type="string">
  ラフネスマップ画像をダウンロードできるURL。
</ResponseField>

<ResponseField name="thumbnail_url" type="string">
  モデルファイルのサムネイル画像をダウンロードできるURL。
</ResponseField>

<ResponseField name="type" type="string">
  Text to 3Dタスクのタイプ。

  可能な値: `text-to-3d-preview`、`text-to-3d-refine`
</ResponseField>

<ResponseField name="video_url" type="string">
  プレビュービデオをダウンロードできるURLを返す非推奨のフィールド。
</ResponseField>

## 例

### 入力

```json theme={null}
{
  "art_style": "realistic",
  "mode": "preview",
  "prompt": "a red cube"
}
```

### 出力

```json theme={null}
{
  "art_style": "realistic",
  "created_at": 1767225600000,
  "finished_at": 1767225719000,
  "id": "018f2c7a-4b1e-7c3d-9a05-6e2f8b41d0c9",
  "model_urls": {
    "fbx": "https://example.invalid/meshy/text-to-3d/model.fbx",
    "glb": "https://example.invalid/meshy/text-to-3d/model.glb",
    "mtl": "https://example.invalid/meshy/text-to-3d/model.mtl",
    "obj": "https://example.invalid/meshy/text-to-3d/model.obj",
    "usdz": "https://example.invalid/meshy/text-to-3d/model.usdz"
  },
  "progress": 100,
  "prompt": "a red cube",
  "started_at": 1767225601000,
  "status": "SUCCEEDED",
  "thumbnail_url": "https://example.invalid/meshy/text-to-3d/thumbnail.png",
  "type": "text-to-3d-preview"
}
```

## 出荷前の確認

SDK は `Idempotency-Key` を生成し、自動リトライで再利用します。手動リトライでは元のキーを再利用してください。Router は最大 10 分間接続を保持できます。

リクエストが失敗すると、Router は理由を説明する `X-Comfy-Error-Type` レスポンスヘッダーを送信します。`422` は、プロバイダーを呼び出す前に Router が入力を拒否したことを意味し、`413` はリクエスト本文が Router の受け入れ可能なサイズを超えていたことを意味します。生成されたアセットは [結果 URL の有効期限](/ja/development/comfy-router/reference#結果アセット) があるため、早めにダウンロードしてください。

上記のフィールド説明に記載されているサイズ制限は、プロバイダーの仕様から引用した、そのフィールドに対するプロバイダー自身の上限です。Router はリクエスト本文全体に対して別の上限を適用し、base64 エンコードされたメディアもこれにカウントされます。[リクエスト本文のサイズ](/ja/development/comfy-router/limitations) を参照してください。

このページは、Comfy Router 経由で呼び出す 1 つのパートナーモデルについて説明しています。同じ `comfy-sdk` / `@comfyorg/sdk` パッケージには、Comfy Cloud 上で ComfyUI のワークフローグラフ全体を実行するための 2 つ目のクライアントも含まれています: `Comfy(api_key=...)` / `new Comfy({ apiKey })`、および `client.workflows`、`client.assets`、`client.jobs`。[Comfy SDKs](/ja/development/api-development/sdks) を参照してください。

<CardGroup cols={3}>
  <Card title="ヘッダー" icon="list" href="/ja/development/comfy-router/headers">
    認証、冪等性、リクエスト ID、エラー分類、リトライ間隔、支出上限。
  </Card>

  <Card title="Router API の利用" icon="code" href="/ja/development/comfy-router/api">
    モデルの検出、バリデーションエラー、リトライ、課金。
  </Card>

  <Card title="制限事項" icon="triangle-exclamation" href="/ja/development/comfy-router/limitations">
    Router が現在対応していないことと、代替手段。
  </Card>
</CardGroup>