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

# Interfaz de generación 3D

> AiHubMix ofrece una API unificada de generación de modelos 3D, compatible con texto a 3D e imagen a 3D, en modo de tarea asíncrona; el primer modelo disponible es Tencent Hunyuan 3D (hy-3d-3.1), con archivos generados en formatos obj / glb / stl / usdz / fbx y materiales PBR

## Inicio rápido

La generación 3D es una operación asíncrona; todo el flujo se divide en tres pasos:

```text theme={null}
1. Enviar la tarea → obtener generation_id
2. Sondear el estado → esperar a que status cambie a completed
3. Descargar los archivos generados → descargar directamente los archivos 3D mediante content_url en output
```

**Ejemplo mínimo**

```shellscript theme={null}
# Paso uno: enviar la tarea de generación 3D (texto a 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": "Un shiba inu con sombrero"
  }'

# Ejemplo de respuesta:
# {
#   "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
# }

# Paso dos: sondear el estado (consultar cada 10~15 segundos hasta que status sea completed)
curl https://aihubmix.com/v1/3d/generations/{generation_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

# Paso tres: descargar los archivos generados (content_url es una dirección temporal, se descarga directamente sin autenticación)
curl "{content_url}" --output model.glb
```

## Resumen de las interfaces

| Interfaz         | Método | Ruta                                 | Descripción                                              |
| :--------------- | :----- | :----------------------------------- | :------------------------------------------------------- |
| Crear tarea 3D   | POST   | `/v1/3d/generations`                 | Enviar la tarea de generación 3D                         |
| Consultar estado | GET    | `/v1/3d/generations/{generation_id}` | Consultar el estado de la tarea y los archivos generados |

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

Método de autenticación: Bearer Token

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

<Note>
  A diferencia de la interfaz de vídeo, la interfaz 3D **no dispone** del endpoint de descarga `/content` ni del endpoint de eliminación `DELETE`: los archivos generados se descargan directamente mediante el `content_url` incluido en `output[]` de la respuesta de consulta.
</Note>

## Modelos compatibles

| Proveedor | Nombre del modelo | Características                                                                                     |
| --------- | ----------------- | --------------------------------------------------------------------------------------------------- |
| Tencent   | `hy-3d-3.1`       | Hunyuan 3D 3.1, compatible con texto a 3D, imagen a 3D y boceto a 3D, con materiales PBR opcionales |

**Tipos de generación (`generate_type`)**

| Tipo       | Descripción                                                                        |
| :--------- | :--------------------------------------------------------------------------------- |
| `Normal`   | Generación estándar (por defecto), geometría + textura                             |
| `Geometry` | Genera solo la malla geométrica sin textura                                        |
| `Sketch`   | Boceto a 3D, permite pasar a la vez la imagen del boceto y la descripción de texto |

## Descripción detallada de la API

### Cabeceras de la petición

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

### Crear tarea de generación 3D

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

#### **Cuerpo de la petición**

| Parámetro          | Tipo   | Obligatorio | Descripción                                                                                                                                                                                                                                                                                                                                         |
| :----------------- | :----- | :---------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model`            | string | Sí          | Nombre del modelo: `hy-3d-3.1`                                                                                                                                                                                                                                                                                                                      |
| `prompt`           | string | Condicional | Descripción de texto, no más de 1024 caracteres; debe pasarse al menos uno entre este parámetro e `input_references`                                                                                                                                                                                                                                |
| `input_references` | array  | Condicional | Array de imágenes de referencia (imagen a 3D), actualmente solo admite 1 imagen; en cada elemento se elige entre `image_url` e `image_base64`                                                                                                                                                                                                       |
| `generate_type`    | string | No          | Tipo de generación: `Normal` (por defecto) / `Geometry` / `Sketch`, sin distinción entre mayúsculas y minúsculas                                                                                                                                                                                                                                    |
| `enable_pbr`       | bool   | No          | Si se generan materiales PBR, por defecto `false`                                                                                                                                                                                                                                                                                                   |
| `face_count`       | int    | No          | Número de caras objetivo, rango `3000` \~ `1500000`; si se omite, lo decide el valor por defecto del modelo                                                                                                                                                                                                                                         |
| `format`           | string | No          | Formato de los archivos generados: `stl` / `usdz` / `fbx`, sin distinción entre mayúsculas y minúsculas; si se omite, se aplica el valor predeterminado del proveedor (Normal suele devolver obj + glb, Geometry solo glb); un formato especificado se genera **de forma adicional** (p. ej., `format: "stl"` devuelve glb + stl, no los reemplaza) |
| `extra_body`       | object | No          | Reenvío transparente del resto de parámetros nativos del upstream (ver la descripción más abajo)                                                                                                                                                                                                                                                    |

**Reglas de validación de parámetros**

* `prompt` e `input_references` son **mutuamente excluyentes** (solo puede pasarse uno); únicamente `generate_type: "Sketch"` permite pasar ambos a la vez (boceto + descripción de texto).
* En cada elemento de `input_references` debe pasarse **exactamente uno** entre `image_url` e `image_base64`:
  * `image_url` solo admite URL públicas `http(s)`, **no admite data URL** (usa `image_base64` en su lugar);
  * `image_base64` no debe superar los **6MB** una vez decodificado.
* `hy-3d-3.1` no admite el tipo de generación `LowPoly`.
* El tamaño total del cuerpo de la petición no debe superar los **10MB**.

<Note>
  **Uso de `extra_body`**: los parámetros nativos del upstream (como `polygon_type`) pueden colocarse en el nivel superior de `extra_body` para su reenvío transparente. Los siguientes parámetros **deben pasarse como campos de nivel superior**; si aparecen en `extra_body` se devolverá un 400: `model`, `prompt`, `image_url`, `image_base64`, `generate_type`, `enable_pbr`, `face_count`, `result_format`; `multi_view_images` (imágenes de múltiples vistas) no se admite por ahora.
</Note>

#### Ejemplo de respuesta

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

#### Descripción de los valores de estado

| Estado        | Descripción                                                                                   |
| :------------ | :-------------------------------------------------------------------------------------------- |
| `queued`      | En cola                                                                                       |
| `in_progress` | Generando                                                                                     |
| `completed`   | Generación completada, `output` incluye las direcciones de descarga de los archivos generados |
| `failed`      | Generación fallida, `error` incluye la información del error                                  |

### Consultar el estado de la tarea

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

Sondea esta interfaz para comprobar si la tarea ha terminado. Se recomienda consultar cada **10\~15 segundos**. Las consultas no se facturan.

#### **Ejemplo de respuesta (generación completada)**

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

**Descripción de los campos de `output[]`**

| Campo         | Descripción                                                                                                       |
| :------------ | :---------------------------------------------------------------------------------------------------------------- |
| `type`        | Tipo de archivo generado (en minúsculas), como `obj`, `glb`, `stl`                                                |
| `b64_json`    | Siempre `null` (los archivos 3D no se devuelven en línea; se descargan de forma unificada mediante `content_url`) |
| `content_url` | Dirección de descarga del archivo generado (enlace temporal del upstream), **descárgalo y guárdalo cuanto antes** |
| `preview_url` | Dirección de la miniatura de vista previa (si el upstream la proporciona)                                         |

<Warning>
  `content_url` y `preview_url` son **enlaces temporales** que expiran pasado un tiempo; descárgalos y transfiérelos a tu propio almacenamiento cuanto antes una vez completada la tarea. El ID de la tarea puede consultarse durante las **24 horas** posteriores a su creación (el campo `expires_at` indica el momento límite de consulta); una vez expirado, la consulta devolverá un error. Los enlaces temporales solo admiten solicitudes GET; las solicitudes HEAD devuelven 403.
</Warning>

## Ejemplos de uso

<CodeGroup>
  ```shellscript Texto a 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": "Una motocicleta de estilo retro steampunk, con acabado de latón y detalles abundantes",
      "enable_pbr": true
    }'
  ```

  ```shellscript Imagen a 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 Imagen a 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 Boceto a 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": "Una aeronave de estilo ciencia ficción con carcasa metálica",
      "input_references": [
        { "image_url": "https://example.com/sketch.png" }
      ]
    }'
  ```

  ```shellscript Especificar número de caras y 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": "Un casco de caballero medieval",
      "generate_type": "Normal",
      "enable_pbr": true,
      "face_count": 40000,
      "format": "fbx"
    }'
  ```
</CodeGroup>

## Ejemplo completo de invocación

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

  # Paso uno: crear la tarea de generación 3D
  response = requests.post(
      f"{BASE_URL}/v1/3d/generations",
      headers=HEADERS,
      json={
          "model": "hy-3d-3.1",
          "prompt": "Un shiba inu con sombrero",
          "enable_pbr": True
      }
  )
  result = response.json()
  generation_id = result["id"]
  print(f"Tarea creada, generation_id: {generation_id}")

  # Paso dos: sondear el estado
  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"Estado actual: {current_status}")

      if current_status == "completed":
          print("¡Generación 3D completada!")
          break
      elif current_status == "failed":
          error = status_data.get("error") or {}
          print(f"Generación fallida: {error.get('message', 'Error desconocido')}")
          exit(1)

      time.sleep(15)  # Consultar cada 15 segundos

  # Paso tres: descargar los archivos generados (content_url es una dirección temporal, descarga directa)
  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"Guardado {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() {
    // Paso uno: crear la tarea
    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: "Un shiba inu con sombrero",
        enable_pbr: true
      })
    });
    const { id: generationId } = await createResponse.json();
    console.log(`Tarea creada: ${generationId}`);

    // Paso dos: sondear el estado
    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(`Estado actual: ${result.status}`);
      if (result.status === "completed" || result.status === "failed") break;
    }

    if (result.status === "failed") {
      console.error(`Generación fallida: ${result.error?.message}`);
      return;
    }

    // Paso tres: descargar los archivos generados
    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(`Guardado model.${item.type}`);
    }
  }

  generate3D();
  ```
</CodeGroup>

## Facturación

* Facturación **por invocación**: el precio lo determina la combinación de `modelo × generate_type × si se activa PBR × si se especifica el número de caras × si se especifica el formato`; consulta los precios concretos en la [galería de modelos](https://aihubmix.com/models).
* El cobro se produce cuando **la tarea se crea correctamente**; consultar el estado de la tarea y descargar los archivos generados no se factura.
* Las combinaciones de parámetros sin precio configurado devuelven directamente un 400 al crear la tarea, sin generar ningún cargo.

## FAQ

### ¿Cuánto tarda la generación 3D?

Suele tardar varios minutos; el tiempo concreto depende del modelo, el tipo de generación y la configuración del número de caras. Se recomienda sondear la interfaz de consulta con un intervalo de 10\~15 segundos.

### ¿Cuál es la validez de los enlaces de los archivos generados y de la tarea?

* El ID de la tarea puede consultarse durante las **24 horas** posteriores a su creación; el campo `expires_at` de la respuesta indica el momento límite de consulta.
* `content_url` / `preview_url` son enlaces temporales del upstream que expiran pasado un tiempo; **descárgalos y transfiérelos cuanto antes** una vez completada la tarea.

### ¿Se pueden pasar `prompt` y la imagen de referencia a la vez?

No; ambos son mutuamente excluyentes. La única excepción es `generate_type: "Sketch"` (boceto a 3D), que permite pasar a la vez la imagen del boceto y la descripción de texto.

### ¿Qué diferencias hay entre los tipos de `generate_type`?

| Tipo       | Descripción                                                  |
| :--------- | :----------------------------------------------------------- |
| `Normal`   | Generación estándar (geometría + textura), valor por defecto |
| `Geometry` | Solo la malla geométrica, sin textura                        |
| `Sketch`   | Boceto a 3D, admite pasar imagen y texto a la vez            |

### ¿Cómo gestionar una tarea fallida?

Cuando `status` sea `failed`, el campo `error` de la respuesta incluirá la información del error:

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

Las causas frecuentes de fallo incluyen: contenido que infringe las políticas, formato de imagen no admitido, imagen de referencia inaccesible, etc. Ajústalo según la información del error y vuelve a intentarlo.

***

Última actualización: 2026-07-17