> ## 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` から直接ダウンロードします。

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

| ベンダー | モデル名 | 特徴 |
| - | - | - |
| 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`（マルチビュー画像）は現在サポートされていません。

#### レスポンス例

```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 を返します。

## 使用サンプル

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

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

```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();
```

## 課金の説明

* **回数**ごとの課金：価格は `モデル × 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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.