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

# Interface de génération 3D

> AiHubMix propose une API unifiée de génération de modèles 3D, prenant en charge le texte vers 3D et l'image vers 3D en mode de tâche asynchrone, avec en premier lieu Tencent Hunyuan 3D (hy-3d-3.1) ; les fichiers produits sont disponibles aux formats obj / glb / stl / usdz / fbx avec matériaux PBR

## Démarrage rapide

La génération 3D est une opération asynchrone, l'ensemble du processus se déroule en trois étapes :

```text theme={null}
1. Soumettre la tâche → obtenir generation_id
2. Interroger le statut → attendre que status passe à completed
3. Télécharger les fichiers → télécharger directement les fichiers 3D via content_url dans output
```

**Exemple minimal**

```shellscript theme={null}
# Étape 1 : soumettre la tâche de génération 3D (texte vers 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 portant un chapeau"
  }'

# Exemple de réponse :
# {
#   "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
# }

# Étape 2 : interroger le statut (toutes les 10 à 15 secondes, jusqu'à ce que status soit completed)
curl https://aihubmix.com/v1/3d/generations/{generation_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

# Étape 3 : télécharger le fichier (content_url est une adresse temporaire, téléchargeable directement sans authentification)
curl "{content_url}" --output model.glb
```

## Aperçu des interfaces

| Interface            | Méthode | Chemin                               | Description                                               |
| :------------------- | :------ | :----------------------------------- | :-------------------------------------------------------- |
| Créer une tâche 3D   | POST    | `/v1/3d/generations`                 | Soumettre une tâche de génération 3D                      |
| Interroger le statut | GET     | `/v1/3d/generations/{generation_id}` | Interroger le statut de la tâche et les fichiers produits |

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

Méthode d'authentification : Bearer Token

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

<Note>
  Contrairement à l'interface vidéo, l'interface 3D **ne dispose pas** de point de terminaison de téléchargement `/content` ni de point de terminaison de suppression `DELETE` : les fichiers produits se téléchargent directement via le champ `content_url` du tableau `output[]` de la réponse d'interrogation.
</Note>

## Modèles pris en charge

| Fournisseur | Nom du modèle | Caractéristiques                                                                                                       |
| ----------- | ------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Tencent     | `hy-3d-3.1`   | Hunyuan 3D 3.1, prise en charge du texte vers 3D, de l'image vers 3D et de l'esquisse vers 3D, matériaux PBR en option |

**Types de génération (`generate_type`)**

| Type       | Description                                                                                        |
| :--------- | :------------------------------------------------------------------------------------------------- |
| `Normal`   | Génération standard (par défaut), géométrie + texture                                              |
| `Geometry` | Génère uniquement la géométrie (maillage brut), sans texture                                       |
| `Sketch`   | Esquisse vers 3D, permet de passer simultanément une image d'esquisse et une description textuelle |

## Description détaillée de l'API

### En-têtes de requête

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

### Créer une tâche de génération 3D

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

#### **Corps de la requête**

| Paramètre          | Type   | Obligatoire  | Description                                                                                                                                                                                                                                                                                                         |
| :----------------- | :----- | :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `model`            | string | Oui          | Nom du modèle : `hy-3d-3.1`                                                                                                                                                                                                                                                                                         |
| `prompt`           | string | Conditionnel | Description textuelle, 1024 caractères maximum ; au moins l'un des deux paramètres `prompt` ou `input_references` doit être fourni                                                                                                                                                                                  |
| `input_references` | array  | Conditionnel | Tableau d'images de référence (image vers 3D), une seule image prise en charge actuellement ; dans chaque élément, fournir soit `image_url`, soit `image_base64`                                                                                                                                                    |
| `generate_type`    | string | Non          | Type de génération : `Normal` (par défaut) / `Geometry` / `Sketch`, insensible à la casse                                                                                                                                                                                                                           |
| `enable_pbr`       | bool   | Non          | Génère ou non des matériaux PBR, par défaut `false`                                                                                                                                                                                                                                                                 |
| `face_count`       | int    | Non          | Nombre de faces cible, plage `3000` \~ `1500000` ; si absent, la valeur par défaut du modèle s'applique                                                                                                                                                                                                             |
| `format`           | string | Non          | Format du fichier produit : `stl` / `usdz` / `fbx`, insensible à la casse ; si absent, la valeur par défaut de l'amont s'applique (Normal renvoie généralement obj + glb, Geometry uniquement glb) ; un format spécifié est généré **en supplément** (par ex. `format: "stl"` renvoie glb + stl, sans remplacement) |
| `extra_body`       | object | Non          | Transmission telle quelle des autres paramètres natifs de l'amont (voir la description ci-dessous)                                                                                                                                                                                                                  |

**Règles de validation des paramètres**

* `prompt` et `input_references` sont **mutuellement exclusifs** (un seul des deux peut être fourni) ; seul `generate_type: "Sketch"` autorise leur passage simultané (esquisse + description textuelle).
* Dans chaque élément de `input_references`, **exactement un** des champs `image_url` et `image_base64` doit être fourni :
  * `image_url` ne prend en charge que les URL publiques `http(s)`, **les data URL ne sont pas prises en charge** (utilisez `image_base64` à la place) ;
  * `image_base64` ne doit pas dépasser **6 Mo** une fois décodé.
* `hy-3d-3.1` ne prend pas en charge le type de génération `LowPoly`.
* La taille totale du corps de la requête ne doit pas dépasser **10 Mo**.

<Note>
  **Utilisation de `extra_body`** : les paramètres natifs de l'amont (par ex. `polygon_type`) peuvent être placés au niveau supérieur de `extra_body` pour être transmis tels quels. Les paramètres suivants **doivent être passés en champs de premier niveau** ; leur présence dans `extra_body` renvoie une erreur 400 : `model`, `prompt`, `image_url`, `image_base64`, `generate_type`, `enable_pbr`, `face_count`, `result_format` ; `multi_view_images` (images multi-vues) n'est pas encore pris en charge.
</Note>

#### Exemple de réponse

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

#### Description des valeurs de statut

| Statut        | Description                                                                                 |
| :------------ | :------------------------------------------------------------------------------------------ |
| `queued`      | En file d'attente                                                                           |
| `in_progress` | En cours de génération                                                                      |
| `completed`   | Génération terminée, `output` contient les adresses de téléchargement des fichiers produits |
| `failed`      | Échec de la génération, `error` contient les informations sur l'erreur                      |

### Interroger le statut de la tâche

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

Interrogez cette interface pour vérifier si la tâche est terminée. Il est recommandé d'interroger toutes les **10 à 15 secondes**. L'interrogation n'est pas facturée.

#### **Exemple de réponse (génération terminée)**

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

**Description des champs de `output[]`**

| Champ         | Description                                                                                                              |
| :------------ | :----------------------------------------------------------------------------------------------------------------------- |
| `type`        | Type du fichier produit (en minuscules), par ex. `obj`, `glb`, `stl`                                                     |
| `b64_json`    | Toujours `null` (les fichiers 3D ne sont pas renvoyés en ligne, le téléchargement passe uniformément par `content_url`)  |
| `content_url` | Adresse de téléchargement du fichier produit (lien temporaire de l'amont), **à télécharger et sauvegarder au plus vite** |
| `preview_url` | Adresse de la miniature de prévisualisation (si fournie par l'amont)                                                     |

<Warning>
  `content_url` et `preview_url` sont des **liens temporaires** qui expirent après un certain temps ; veuillez télécharger et transférer les fichiers vers votre propre stockage dès que la tâche est terminée. L'ID de tâche reste interrogeable pendant **24 heures** à compter de sa création (le champ `expires_at` indique l'échéance d'interrogation) ; passé ce délai, l'interrogation renvoie une erreur. Les liens temporaires ne prennent en charge que les requêtes GET ; les requêtes HEAD renvoient une erreur 403.
</Warning>

## Exemples d'utilisation

<CodeGroup>
  ```shellscript Texte vers 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": "Une moto de style steampunk rétro, finition laiton, riche en détails",
      "enable_pbr": true
    }'
  ```

  ```shellscript Image vers 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 Image vers 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 Esquisse vers 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": "Un vaisseau volant de style science-fiction, coque métallique",
      "input_references": [
        { "image_url": "https://example.com/sketch.png" }
      ]
    }'
  ```

  ```shellscript Nombre de faces et format 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 casque de chevalier médiéval",
      "generate_type": "Normal",
      "enable_pbr": true,
      "face_count": 40000,
      "format": "fbx"
    }'
  ```
</CodeGroup>

## Exemple d'appel complet

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

  # Étape 1 : créer la tâche de génération 3D
  response = requests.post(
      f"{BASE_URL}/v1/3d/generations",
      headers=HEADERS,
      json={
          "model": "hy-3d-3.1",
          "prompt": "Un shiba inu portant un chapeau",
          "enable_pbr": True
      }
  )
  result = response.json()
  generation_id = result["id"]
  print(f"Tâche créée, generation_id : {generation_id}")

  # Étape 2 : interroger le statut
  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"Statut actuel : {current_status}")

      if current_status == "completed":
          print("Génération 3D terminée !")
          break
      elif current_status == "failed":
          error = status_data.get("error") or {}
          print(f"Échec de la génération : {error.get('message', 'Erreur inconnue')}")
          exit(1)

      time.sleep(15)  # interroger toutes les 15 secondes

  # Étape 3 : télécharger les fichiers (content_url est une adresse temporaire, téléchargement direct)
  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} sauvegardé ({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() {
    // Étape 1 : créer la tâche
    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 portant un chapeau",
        enable_pbr: true
      })
    });
    const { id: generationId } = await createResponse.json();
    console.log(`Tâche créée : ${generationId}`);

    // Étape 2 : interroger le statut
    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(`Statut actuel : ${result.status}`);
      if (result.status === "completed" || result.status === "failed") break;
    }

    if (result.status === "failed") {
      console.error(`Échec de la génération : ${result.error?.message}`);
      return;
    }

    // Étape 3 : télécharger les fichiers
    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} sauvegardé`);
    }
  }

  generate3D();
  ```
</CodeGroup>

## Facturation

* Facturation **à la tâche** : le prix est déterminé par la combinaison `modèle × generate_type × activation du PBR × nombre de faces spécifié × format spécifié` ; les tarifs détaillés sont disponibles sur la [galerie de modèles](https://aihubmix.com/models).
* La facturation intervient au moment de la **création réussie de la tâche** ; l'interrogation du statut et le téléchargement des fichiers ne sont pas facturés.
* Une combinaison de paramètres sans tarif configuré renvoie directement une erreur 400 à la création, sans aucun débit.

## FAQ

### Combien de temps prend la génération 3D ?

Généralement plusieurs minutes, le temps exact dépend du modèle, du type de génération et du nombre de faces défini. Il est recommandé d'interroger l'interface de consultation à un intervalle de 10 à 15 secondes.

### Quelle est la durée de validité des liens de fichiers et de la tâche ?

* L'ID de tâche reste interrogeable pendant **24 heures** à compter de sa création ; le champ `expires_at` de la réponse indique l'échéance d'interrogation.
* `content_url` / `preview_url` sont des liens temporaires de l'amont qui expirent après un certain temps ; veuillez **télécharger et sauvegarder au plus vite** une fois la tâche terminée.

### Peut-on passer `prompt` et une image de référence en même temps ?

Non, les deux sont mutuellement exclusifs — la seule exception est `generate_type: "Sketch"` (esquisse vers 3D), qui autorise le passage simultané d'une image d'esquisse et d'une description textuelle.

### Quelles sont les différences entre les types de `generate_type` ?

| Type       | Description                                                  |
| :--------- | :----------------------------------------------------------- |
| `Normal`   | Génération standard (géométrie + texture), valeur par défaut |
| `Geometry` | Géométrie seule (maillage brut), sans texture                |
| `Sketch`   | Esquisse vers 3D, image et texte acceptés simultanément      |

### Que faire en cas d'échec de la tâche ?

Lorsque `status` est `failed`, le champ `error` de la réponse contient les informations sur l'erreur :

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

Les causes courantes d'échec incluent : contenu non conforme, format d'image non pris en charge, image de référence inaccessible, etc. Veuillez ajuster en fonction du message d'erreur puis réessayer.

***

Dernière mise à jour : 2026-07-17