> ## 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 생성 API

> AiHubMix는 텍스트-3D와 이미지-3D를 지원하는 통합 3D 모델 생성 API를 제공합니다. 비동기 작업 방식이며, 첫 번째로 Tencent Hunyuan 3D(hy-3d-3.1)를 지원하고 결과물은 obj / glb / stl / usdz / fbx 형식과 PBR 재질을 지원합니다

## 빠른 시작

3D 생성은 비동기 작업이며, 전체 프로세스는 세 단계로 나뉩니다.

```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은 임시 주소이며, 인증 없이 직접 다운로드 가능)
curl "{content_url}" --output model.glb
```

## API 개요

| API      | 메서드  | 경로                                   | 설명             |
| :------- | :--- | :----------------------------------- | :------------- |
| 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>
  비디오 API와 달리, 3D API에는 `/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`는 **정확히 하나만** 전달해야 합니다:
  * `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`에 결과물 다운로드 주소 포함 |
| `failed`      | 생성 실패, `error`에 오류 정보 포함        |

### 작업 상태 조회

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

이 API를 폴링하여 작업 완료 여부를 확인합니다. **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` | 결과물 다운로드 주소(업스트림 임시 링크), **가능한 한 빨리 다운로드하여 저장하세요**           |
| `preview_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은 임시 주소, 직접 다운로드)
  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초 간격으로 조회 API를 폴링하는 것을 권장합니다.

### 결과물 링크와 작업의 유효 기간은 얼마나 되나요?

* 작업 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