> ## 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.

# API de Geração 3D

> A AiHubMix oferece uma API unificada de geração de modelos 3D, com suporte a texto para 3D e imagem para 3D em modo de tarefa assíncrona, inicialmente com o Tencent Hunyuan 3D (hy-3d-3.1), e arquivos gerados nos formatos obj / glb / stl / usdz / fbx com materiais PBR

## Início Rápido

A geração 3D é uma operação assíncrona, e todo o fluxo é dividido em três etapas:

```text theme={null}
1. Enviar tarefa → obter generation_id
2. Consultar status → aguardar status mudar para completed
3. Baixar os arquivos gerados → baixar o arquivo 3D diretamente pelo content_url em output
```

**Exemplo mais simples**

```shellscript theme={null}
# Etapa 1: Enviar a tarefa de geração 3D (texto para 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": "Um cachorro Shiba Inu usando um chapéu"
  }'

# Exemplo de resposta:
# {
#   "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
# }

# Etapa 2: Consultar o status (consulte a cada 10~15 segundos, até que status seja completed)
curl https://aihubmix.com/v1/3d/generations/{generation_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

# Etapa 3: Baixar os arquivos gerados (content_url é um endereço temporário, com download direto, sem autenticação)
curl "{content_url}" --output model.glb
```

## Visão Geral das Interfaces

| Interface        | Método | Caminho                              | Descrição                                          |
| :--------------- | :----- | :----------------------------------- | :------------------------------------------------- |
| Criar tarefa 3D  | POST   | `/v1/3d/generations`                 | Enviar tarefa de geração 3D                        |
| Consultar status | GET    | `/v1/3d/generations/{generation_id}` | Consultar o status da tarefa e os arquivos gerados |

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

Método de autenticação: Bearer Token

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

<Note>
  Diferentemente da interface de vídeo, a interface 3D **não possui** o endpoint de download `/content` nem o endpoint de exclusão `DELETE`: os arquivos gerados são baixados diretamente pelo `content_url` presente em `output[]` da resposta de consulta.
</Note>

## Modelos Suportados

| Fornecedor | Nome do modelo | Características                                                                                           |
| ---------- | -------------- | --------------------------------------------------------------------------------------------------------- |
| Tencent    | `hy-3d-3.1`    | Hunyuan 3D 3.1, com suporte a texto para 3D, imagem para 3D e esboço para 3D, com materiais PBR opcionais |

**Tipos de geração (`generate_type`)**

| Tipo       | Descrição                                                                                |
| :--------- | :--------------------------------------------------------------------------------------- |
| `Normal`   | Geração padrão (valor padrão), geometria + textura                                       |
| `Geometry` | Gera apenas a malha geométrica, sem textura                                              |
| `Sketch`   | Esboço para 3D, permite enviar simultaneamente a imagem do esboço e a descrição em texto |

## Detalhes da API

### Cabeçalhos da requisição

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

### Criar tarefa de geração 3D

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

#### **Corpo da requisição**

| Parâmetro          | Tipo   | Obrigatório | Descrição                                                                                                                                                                                                                                                                                                          |
| :----------------- | :----- | :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model`            | string | Sim         | Nome do modelo: `hy-3d-3.1`                                                                                                                                                                                                                                                                                        |
| `prompt`           | string | Condicional | Descrição em texto, com no máximo 1024 caracteres; envie ao menos um entre este e `input_references`                                                                                                                                                                                                               |
| `input_references` | array  | Condicional | Array de imagens de referência (imagem para 3D), atualmente com suporte a apenas 1 imagem; em cada item, escolha entre `image_url` e `image_base64`                                                                                                                                                                |
| `generate_type`    | string | Não         | Tipo de geração: `Normal` (padrão) / `Geometry` / `Sketch`, sem distinção entre maiúsculas e minúsculas                                                                                                                                                                                                            |
| `enable_pbr`       | bool   | Não         | Se gera materiais PBR, padrão `false`                                                                                                                                                                                                                                                                              |
| `face_count`       | int    | Não         | Número de faces alvo, intervalo `3000` \~ `1500000`; se ausente, o valor padrão é decidido pelo modelo                                                                                                                                                                                                             |
| `format`           | string | Não         | Formato do arquivo gerado: `stl` / `usdz` / `fbx`, sem distinção entre maiúsculas e minúsculas; se ausente, aplica-se o padrão do upstream (Normal geralmente retorna obj + glb, Geometry apenas glb); um formato especificado é gerado **adicionalmente** (ex.: `format: "stl"` retorna glb + stl, não substitui) |
| `extra_body`       | object | Não         | Repasse dos demais parâmetros nativos do upstream (veja a descrição abaixo)                                                                                                                                                                                                                                        |

**Regras de validação dos parâmetros**

* `prompt` e `input_references` são **mutuamente exclusivos** (envie apenas um deles); somente `generate_type: "Sketch"` permite enviar os dois simultaneamente (esboço + descrição em texto).
* Em cada item de `input_references`, deve ser enviado **exatamente um** entre `image_url` e `image_base64`:
  * `image_url` aceita apenas URLs públicas `http(s)`, **sem suporte a data URL** (use `image_base64` em vez disso);
  * `image_base64` não pode exceder **6MB** após a decodificação.
* O `hy-3d-3.1` não suporta o tipo de geração `LowPoly`.
* O tamanho total do corpo da requisição não pode exceder **10MB**.

<Note>
  **Uso de `extra_body`**: os parâmetros nativos do upstream (como `polygon_type`) podem ser colocados no nível superior de `extra_body` para repasse. Os parâmetros a seguir **devem ser enviados como campos de nível superior** — se aparecerem em `extra_body`, será retornado 400: `model`, `prompt`, `image_url`, `image_base64`, `generate_type`, `enable_pbr`, `face_count`, `result_format`; `multi_view_images` (imagens de múltiplas vistas) ainda não é suportado.
</Note>

#### Exemplo de resposta

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

#### Descrição dos valores de status

| Status        | Descrição                                                                    |
| :------------ | :--------------------------------------------------------------------------- |
| `queued`      | Na fila                                                                      |
| `in_progress` | Em geração                                                                   |
| `completed`   | Geração concluída, `output` contém os links de download dos arquivos gerados |
| `failed`      | Falha na geração, `error` contém a informação do erro                        |

### Consultar status da tarefa

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

Consulte esta interface para verificar se a tarefa foi concluída. Recomenda-se consultar a cada **10\~15 segundos**. A consulta não é cobrada.

#### **Exemplo de resposta (geração concluída)**

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

**Campos de `output[]`**

| Campo         | Descrição                                                                                              |
| :------------ | :----------------------------------------------------------------------------------------------------- |
| `type`        | Tipo do arquivo gerado (minúsculas), como `obj`, `glb`, `stl`                                          |
| `b64_json`    | Sempre `null` (os arquivos 3D não são retornados inline; o download é feito sempre pelo `content_url`) |
| `content_url` | Link de download do arquivo gerado (link temporário do upstream), **baixe e salve o quanto antes**     |
| `preview_url` | Link da miniatura de pré-visualização (quando fornecido pelo upstream)                                 |

<Warning>
  `content_url` e `preview_url` são **links temporários** e expiram após algum tempo; baixe e transfira para o seu próprio armazenamento assim que a tarefa for concluída. O ID da tarefa pode ser consultado por **24 horas** a partir da criação (o campo `expires_at` indica o momento limite de consulta); após a expiração, a consulta retornará erro. Os links temporários aceitam apenas requisições GET; requisições HEAD retornam 403.
</Warning>

## Exemplos de Uso

<CodeGroup>
  ```shellscript Texto para 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": "Uma motocicleta retrô em estilo steampunk, com acabamento em latão e detalhes ricos",
      "enable_pbr": true
    }'
  ```

  ```shellscript Imagem para 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 Imagem para 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 Esboço para 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": "Uma aeronave em estilo de ficção científica, com casco metálico",
      "input_references": [
        { "image_url": "https://example.com/sketch.png" }
      ]
    }'
  ```

  ```shellscript Definir número de faces e formato 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": "Um elmo de cavaleiro medieval",
      "generate_type": "Normal",
      "enable_pbr": true,
      "face_count": 40000,
      "format": "fbx"
    }'
  ```
</CodeGroup>

## Exemplos Completos de Chamada

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

  # Etapa 1: Criar a tarefa de geração 3D
  response = requests.post(
      f"{BASE_URL}/v1/3d/generations",
      headers=HEADERS,
      json={
          "model": "hy-3d-3.1",
          "prompt": "Um cachorro Shiba Inu usando um chapéu",
          "enable_pbr": True
      }
  )
  result = response.json()
  generation_id = result["id"]
  print(f"Tarefa criada, generation_id: {generation_id}")

  # Etapa 2: Consultar o status
  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"Status atual: {current_status}")

      if current_status == "completed":
          print("Geração 3D concluída!")
          break
      elif current_status == "failed":
          error = status_data.get("error") or {}
          print(f"Falha na geração: {error.get('message', 'Erro desconhecido')}")
          exit(1)

      time.sleep(15)  # Consulta a cada 15 segundos

  # Etapa 3: Baixar os arquivos gerados (content_url é um endereço temporário, com download direto)
  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"Arquivo {file_name} salvo ({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() {
    // Etapa 1: Criar a tarefa
    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: "Um cachorro Shiba Inu usando um chapéu",
        enable_pbr: true
      })
    });
    const { id: generationId } = await createResponse.json();
    console.log(`Tarefa criada: ${generationId}`);

    // Etapa 2: Consultar o status
    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(`Status atual: ${result.status}`);
      if (result.status === "completed" || result.status === "failed") break;
    }

    if (result.status === "failed") {
      console.error(`Falha na geração: ${result.error?.message}`);
      return;
    }

    // Etapa 3: Baixar os arquivos gerados
    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(`Arquivo model.${item.type} salvo`);
    }
  }

  generate3D();
  ```
</CodeGroup>

## Cobrança

* Cobrança por **execução**: o preço é determinado pela combinação de `modelo × generate_type × ativação de PBR × definição de número de faces × definição de formato`; veja os preços na [Galeria de Modelos](https://aihubmix.com/models).
* A cobrança ocorre no momento da **criação bem-sucedida da tarefa**; consultar o status da tarefa e baixar os arquivos gerados não são tarifados.
* Combinações de parâmetros sem preço configurado retornam 400 diretamente na criação, sem gerar cobrança.

## FAQ

### Quanto tempo leva a geração 3D?

Normalmente leva alguns minutos, dependendo do modelo, do tipo de geração e da configuração do número de faces. Recomenda-se consultar a interface de consulta em intervalos de 10\~15 segundos.

### Qual é a validade dos links dos arquivos gerados e da tarefa?

* O ID da tarefa pode ser consultado por **24 horas** a partir da criação; o campo `expires_at` na resposta indica o momento limite de consulta.
* `content_url` / `preview_url` são links temporários do upstream e expiram após algum tempo; **baixe e salve o quanto antes** após a conclusão da tarefa.

### Posso enviar `prompt` e imagem de referência ao mesmo tempo?

Não, os dois são mutuamente exclusivos — a única exceção é `generate_type: "Sketch"` (esboço para 3D), que permite enviar simultaneamente a imagem do esboço e a descrição em texto.

### Qual é a diferença entre os tipos de `generate_type`?

| Tipo       | Descrição                                                    |
| :--------- | :----------------------------------------------------------- |
| `Normal`   | Geração padrão (geometria + textura), valor padrão           |
| `Geometry` | Apenas a malha geométrica, sem textura                       |
| `Sketch`   | Esboço para 3D, permite enviar imagem e texto ao mesmo tempo |

### O que fazer quando a tarefa falha?

Quando o `status` for `failed`, o campo `error` na resposta conterá a informação do erro:

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

As causas comuns de falha incluem: violação de conteúdo, formato de imagem não suportado, imagem de referência inacessível, entre outros. Ajuste de acordo com a informação do erro e tente novamente.

***

Última atualização: 2026-07-17