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

# 3D 生成インターフェース

> AiHubMix は統一された 3D モデル生成 API を提供し、テキストから 3D と画像から 3D に対応した非同期タスクモードで、第一弾として Tencent Hunyuan 3D（hy-3d-3.1）をサポートし、成果物は obj / glb / stl / usdz / fbx 形式と PBR マテリアルに対応します

## クイックスタート

3D 生成は非同期処理であり、全体のフローは3つのステップに分かれます：

```text theme={null}
1. タスクを送信 → generation_id を取得
2. ステータスをポーリング → status が completed になるまで待機
3. 成果物をダウンロード → output 内の content_url から 3D ファイルを直接ダウンロード
```

**最小サンプル**

```shellscript theme={null}
# ステップ1：3D 生成タスクを送信（テキストから 3D）
curl -X POST https://aihubmix.com/v1/3d/generations \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hy-3d-3.1",
    "prompt": "帽子をかぶった柴犬"
  }'

# レスポンス例：
# {
#   "id": "eyJtb2RlbCI6Imh5LTNkLTMuMSIsIml...",
#   "object": "3d.generation",
#   "model": "hy-3d-3.1",
#   "status": "queued",
#   "output": null,
#   "error": null,
#   "created_at": 1752728000,
#   "completed_at": null,
#   "expires_at": 1752814400
# }

# ステップ2：ステータスをポーリング（10~15 秒ごとに照会し、status が completed になるまで）
curl https://aihubmix.com/v1/3d/generations/{generation_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

# ステップ3：成果物をダウンロード（content_url は一時的な URL で、認証不要で直接ダウンロード可能）
curl "{content_url}" --output model.glb
```

## インターフェース概要

| インターフェース | メソッド | パス                                   | 説明               |
| :------- | :--- | :----------------------------------- | :--------------- |
| 3D タスク作成 | POST | `/v1/3d/generations`                 | 3D 生成タスクを送信      |
| ステータス照会  | GET  | `/v1/3d/generations/{generation_id}` | タスクのステータスと成果物を照会 |

Base URL：`https://aihubmix.com`

認証方式：Bearer Token

```shellscript theme={null}
Authorization: Bearer $AIHUBMIX_API_KEY
```

<Note>
  動画インターフェースとは異なり、3D インターフェースには `/content` ダウンロードエンドポイントおよび `DELETE` 削除エンドポイントは**ありません**。成果物は照会レスポンスの `output[]` に含まれる `content_url` から直接ダウンロードします。
</Note>

## サポートされているモデル

| ベンダー    | モデル名        | 特徴                                                              |
| ------- | ----------- | --------------------------------------------------------------- |
| Tencent | `hy-3d-3.1` | Hunyuan 3D 3.1、テキストから 3D・画像から 3D・スケッチから 3D をサポート、PBR マテリアルを選択可能 |

**生成タイプ（`generate_type`）**

| タイプ        | 説明                              |
| :--------- | :------------------------------ |
| `Normal`   | 標準生成（デフォルト）、ジオメトリ + テクスチャ       |
| `Geometry` | ジオメトリのみのホワイトモデルを生成、テクスチャなし      |
| `Sketch`   | スケッチから 3D、スケッチ画像とテキスト記述の同時指定が可能 |

## API 詳細説明

### リクエストヘッダー

```shellscript theme={null}
Authorization: Bearer $AIHUBMIX_API_KEY
Content-Type: application/json
```

### 3D 生成タスクの作成

```shellscript theme={null}
POST /v1/3d/generations
```

#### **リクエストボディ**

| パラメータ              | 型      | 必須   | 説明                                                                                                                                                                      |
| :----------------- | :----- | :--- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model`            | string | はい   | モデル名：`hy-3d-3.1`                                                                                                                                                        |
| `prompt`           | string | 条件付き | テキスト記述、1024 文字以内；`input_references` と少なくともどちらか一方を指定                                                                                                                     |
| `input_references` | array  | 条件付き | 参考画像の配列（画像から 3D）、現在は 1 枚のみサポート；各項目内で `image_url` と `image_base64` のどちらか一方を指定                                                                                            |
| `generate_type`    | string | いいえ  | 生成タイプ：`Normal`（デフォルト）/ `Geometry` / `Sketch`、大文字・小文字を区別しない                                                                                                              |
| `enable_pbr`       | bool   | いいえ  | PBR マテリアルを生成するか、デフォルト `false`                                                                                                                                           |
| `face_count`       | int    | いいえ  | 目標面数、範囲 `3000`\~`1500000`；未指定の場合はモデルのデフォルトに従う                                                                                                                           |
| `format`           | string | いいえ  | 成果物の形式：`stl` / `usdz` / `fbx`、大文字・小文字を区別しない；未指定の場合は上流のデフォルトに従う（Normal は通常 obj + glb、Geometry は glb のみ）；形式を指定すると**追加**で生成される（例：`format: "stl"` は glb + stl を返し、置き換えではない） |
| `extra_body`       | object | いいえ  | その他の上流ネイティブパラメータをパススルー（下記の説明を参照）                                                                                                                                        |

**パラメータ検証ルール**

* `prompt` と `input_references` は**排他**です（どちらか一方のみ指定可能）。`generate_type: "Sketch"` の場合のみ、両方の同時指定（スケッチ + テキスト記述）が許可されます。
* `input_references` の各項目では `image_url` と `image_base64` のうち**ちょうど 1 つ**を指定する必要があります：
  * `image_url` は `http(s)` の公開 URL のみサポートし、**data URL はサポートしません**（`image_base64` を使用してください）；
  * `image_base64` はデコード後 **6MB** 以内である必要があります。
* `hy-3d-3.1` は `LowPoly` 生成タイプをサポートしません。
* リクエストボディの合計サイズは **10MB** 以内である必要があります。

<Note>
  **`extra_body` の使用について**：上流のネイティブパラメータ（`polygon_type` など）は `extra_body` のトップレベルに入れてパススルーできます。以下のパラメータは**必ずトップレベルフィールド**として指定してください。`extra_body` 内に含めると 400 が返されます：`model`、`prompt`、`image_url`、`image_base64`、`generate_type`、`enable_pbr`、`face_count`、`result_format`；`multi_view_images`（マルチビュー画像）は現在サポートされていません。
</Note>

#### レスポンス例

```json theme={null}
{
  "id": "eyJtb2RlbCI6Imh5LTNkLTMuMSIsIml...",
  "object": "3d.generation",
  "model": "hy-3d-3.1",
  "status": "queued",
  "output": null,
  "error": null,
  "created_at": 1752728000,
  "completed_at": null,
  "expires_at": 1752814400
}
```

#### ステータス値の説明

| ステータス         | 説明                                  |
| :------------ | :---------------------------------- |
| `queued`      | 待機中                                 |
| `in_progress` | 生成中                                 |
| `completed`   | 生成完了、`output` に成果物のダウンロード URL が含まれる |
| `failed`      | 生成失敗、`error` にエラー情報が含まれる            |

### タスクステータスの照会

```shellscript theme={null}
GET /v1/3d/generations/{generation_id}
```

このインターフェースをポーリングしてタスクが完了したか確認します。**10\~15 秒** ごとに照会することを推奨します。照会は課金対象外です。

#### **レスポンス例（生成完了）**

```json theme={null}
{
  "id": "eyJtb2RlbCI6Imh5LTNkLTMuMSIsIml...",
  "object": "3d.generation",
  "model": "hy-3d-3.1",
  "status": "completed",
  "output": [
    {
      "type": "obj",
      "b64_json": null,
      "content_url": "https://example-cos.tencentcos.cn/.../model.obj?sign=...",
      "preview_url": "https://example-cos.tencentcos.cn/.../preview.png?sign=..."
    },
    {
      "type": "glb",
      "b64_json": null,
      "content_url": "https://example-cos.tencentcos.cn/.../model.glb?sign=..."
    }
  ],
  "error": null,
  "created_at": 1752728000,
  "completed_at": 1752728180,
  "expires_at": 1752814400
}
```

**`output[]` フィールドの説明**

| フィールド         | 説明                                                       |
| :------------ | :------------------------------------------------------- |
| `type`        | 成果物のファイルタイプ（小文字）、例：`obj`、`glb`、`stl`                     |
| `b64_json`    | 常に `null`（3D 成果物はインラインで返されず、統一して `content_url` からダウンロード） |
| `content_url` | 成果物のダウンロード URL（上流の一時リンク）、**速やかにダウンロードして保存してください**        |
| `preview_url` | プレビューサムネイルの URL（上流が提供する場合）                               |

<Warning>
  `content_url` と `preview_url` は**一時リンク**であり、一定時間後に有効期限が切れます。タスク完了後は速やかにダウンロードし、ご自身のストレージへ転送保存してください。タスク ID は作成から **24 時間**以内照会可能です（`expires_at` フィールドが照会期限の時刻です）。期限切れ後の照会はエラーを返します。一時リンクは GET リクエストのみをサポートし、HEAD リクエストは 403 を返します。
</Warning>

## 使用サンプル

<CodeGroup>
  ```shellscript テキストから 3D theme={null}
  curl -X POST https://aihubmix.com/v1/3d/generations \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "hy-3d-3.1",
      "prompt": "レトロなスチームパンク風のバイク、真鍮の質感、豊富なディテール",
      "enable_pbr": true
    }'
  ```

  ```shellscript 画像から 3D（URL） theme={null}
  curl -X POST https://aihubmix.com/v1/3d/generations \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "hy-3d-3.1",
      "input_references": [
        { "image_url": "https://example.com/cat.png" }
      ]
    }'
  ```

  ```shellscript 画像から 3D（Base64） theme={null}
  curl -X POST https://aihubmix.com/v1/3d/generations \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "hy-3d-3.1",
      "input_references": [
        { "image_base64": "<BASE64_ENCODED_IMAGE>" }
      ]
    }'
  ```

  ```shellscript スケッチから 3D（Sketch） theme={null}
  curl -X POST https://aihubmix.com/v1/3d/generations \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "hy-3d-3.1",
      "generate_type": "Sketch",
      "prompt": "SF 風の飛行体、金属の外装",
      "input_references": [
        { "image_url": "https://example.com/sketch.png" }
      ]
    }'
  ```

  ```shellscript 面数と形式を指定 theme={null}
  curl -X POST https://aihubmix.com/v1/3d/generations \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "hy-3d-3.1",
      "prompt": "中世の騎士のヘルメット",
      "generate_type": "Normal",
      "enable_pbr": true,
      "face_count": 40000,
      "format": "fbx"
    }'
  ```
</CodeGroup>

## 完全な呼び出しサンプル

<CodeGroup>
  ```python Python theme={null}
  import requests
  import time

  API_KEY = "AIHUBMIX_API_KEY"
  BASE_URL = "https://aihubmix.com"
  HEADERS = {
      "Authorization": f"Bearer {API_KEY}",
      "Content-Type": "application/json"
  }

  # ステップ1：3D 生成タスクを作成
  response = requests.post(
      f"{BASE_URL}/v1/3d/generations",
      headers=HEADERS,
      json={
          "model": "hy-3d-3.1",
          "prompt": "帽子をかぶった柴犬",
          "enable_pbr": True
      }
  )
  result = response.json()
  generation_id = result["id"]
  print(f"タスクが作成されました、generation_id: {generation_id}")

  # ステップ2：ステータスをポーリング
  while True:
      status_response = requests.get(
          f"{BASE_URL}/v1/3d/generations/{generation_id}",
          headers=HEADERS
      )
      status_data = status_response.json()
      current_status = status_data["status"]
      print(f"現在のステータス: {current_status}")

      if current_status == "completed":
          print("3D 生成完了！")
          break
      elif current_status == "failed":
          error = status_data.get("error") or {}
          print(f"生成失敗: {error.get('message', '不明なエラー')}")
          exit(1)

      time.sleep(15)  # 15 秒ごとに照会

  # ステップ3：成果物をダウンロード（content_url は一時的な URL、直接ダウンロード）
  for item in status_data["output"]:
      file_url = item["content_url"]
      file_name = f"model.{item['type']}"
      file_response = requests.get(file_url)
      with open(file_name, "wb") as f:
          f.write(file_response.content)
      print(f"{file_name} を保存しました（{len(file_response.content) / 1024 / 1024:.1f} MB）")
  ```

  ```javascript Node.js theme={null}
  const API_KEY = "your_aihubmix_api_key";
  const BASE_URL = "https://aihubmix.com";

  async function generate3D() {
    // ステップ1：タスクを作成
    const createResponse = await fetch(`${BASE_URL}/v1/3d/generations`, {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${API_KEY}`,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        model: "hy-3d-3.1",
        prompt: "帽子をかぶった柴犬",
        enable_pbr: true
      })
    });
    const { id: generationId } = await createResponse.json();
    console.log(`タスクが作成されました: ${generationId}`);

    // ステップ2：ステータスをポーリング
    let result;
    while (true) {
      await new Promise(resolve => setTimeout(resolve, 15000));
      const statusResponse = await fetch(
        `${BASE_URL}/v1/3d/generations/${generationId}`,
        { headers: { "Authorization": `Bearer ${API_KEY}` } }
      );
      result = await statusResponse.json();
      console.log(`現在のステータス: ${result.status}`);
      if (result.status === "completed" || result.status === "failed") break;
    }

    if (result.status === "failed") {
      console.error(`生成失敗: ${result.error?.message}`);
      return;
    }

    // ステップ3：成果物をダウンロード
    const fs = require("fs");
    for (const item of result.output) {
      const fileResponse = await fetch(item.content_url);
      const buffer = Buffer.from(await fileResponse.arrayBuffer());
      fs.writeFileSync(`model.${item.type}`, buffer);
      console.log(`model.${item.type} を保存しました`);
    }
  }

  generate3D();
  ```
</CodeGroup>

## 課金の説明

* **回数**ごとの課金：価格は `モデル × generate_type × PBR の有無 × 面数指定の有無 × 形式指定の有無` の組み合わせで決まります。具体的な価格は[モデル広場](https://aihubmix.com/models)を参照してください。
* 課金は**タスク作成成功時**に発生します。タスクステータスの照会と成果物のダウンロードは課金対象外です。
* 価格が設定されていないパラメータの組み合わせは、作成時に直接 400 を返し、課金は発生しません。

## FAQ

### 3D 生成にはどのくらい時間がかかりますか？

通常は数分かかり、具体的な時間はモデル、生成タイプ、面数の設定によって異なります。10\~15 秒の間隔で照会インターフェースをポーリングすることを推奨します。

### 成果物リンクとタスクの有効期限はどのくらいですか？

* タスク ID は作成から **24 時間**以内照会可能で、レスポンスの `expires_at` フィールドが照会期限の時刻です。
* `content_url` / `preview_url` は上流の一時リンクであり、一定時間後に有効期限が切れます。タスク完了後は**速やかにダウンロードして転送保存**してください。

### `prompt` と参考画像を同時に指定できますか？

できません。両者は排他です。唯一の例外は `generate_type: "Sketch"`（スケッチから 3D）で、スケッチ画像とテキスト記述の同時指定が許可されます。

### `generate_type` の各タイプにはどんな違いがありますか？

| タイプ        | 説明                         |
| :--------- | :------------------------- |
| `Normal`   | 標準生成（ジオメトリ + テクスチャ）、デフォルト値 |
| `Geometry` | ジオメトリのみのホワイトモデル、テクスチャなし    |
| `Sketch`   | スケッチから 3D、画像とテキストの同時指定が可能  |

### タスクが失敗した場合の対処は？

`status` が `failed` の場合、レスポンスの `error` フィールドにエラー情報が含まれます：

```json theme={null}
{
  "status": "failed",
  "error": {
    "message": "...",
    "type": "z3d_generation_error"
  }
}
```

よくある失敗原因には、コンテンツ違反、画像形式が非対応、参考画像へアクセスできないなどがあります。エラー情報に基づいて調整してから再試行してください。

***

最終更新：2026-07-17