> ## 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-Generierungs-API

> AiHubMix bietet eine einheitliche API zur Generierung von 3D-Modellen, unterstützt Text-zu-3D und Bild-zu-3D im asynchronen Aufgabenmodus, zunächst mit Tencent Hunyuan 3D (hy-3d-3.1); Ergebnisse in den Formaten obj / glb / stl / usdz / fbx mit PBR-Materialien

## Schnellstart

Die 3D-Generierung ist ein asynchroner Vorgang. Der gesamte Ablauf gliedert sich in drei Schritte:

```text theme={null}
1. Aufgabe übermitteln → generation_id erhalten
2. Status abfragen → warten, bis status auf completed wechselt
3. Ergebnis herunterladen → 3D-Datei direkt über die content_url in output herunterladen
```

**Minimalbeispiel**

```shellscript theme={null}
# Schritt 1: 3D-Generierungsaufgabe übermitteln (Text-zu-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": "Ein Shiba Inu mit Hut"
  }'

# Beispielantwort:
# {
#   "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
# }

# Schritt 2: Status abfragen (alle 10–15 Sekunden abfragen, bis status auf completed steht)
curl https://aihubmix.com/v1/3d/generations/{generation_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

# Schritt 3: Ergebnis herunterladen (content_url ist eine temporäre Adresse, direkter Download ohne Authentifizierung)
curl "{content_url}" --output model.glb
```

## Übersicht der Schnittstellen

| Schnittstelle        | Methode | Pfad                                 | Beschreibung                           |
| :------------------- | :------ | :----------------------------------- | :------------------------------------- |
| 3D-Aufgabe erstellen | POST    | `/v1/3d/generations`                 | 3D-Generierungsaufgabe übermitteln     |
| Status abfragen      | GET     | `/v1/3d/generations/{generation_id}` | Aufgabenstatus und Ergebnisse abfragen |

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

Authentifizierungsmethode: Bearer Token

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

<Note>
  Anders als die Video-API besitzt die 3D-API **keinen** `/content`-Download-Endpunkt und keinen `DELETE`-Endpunkt: Die Ergebnisse werden direkt über die `content_url` in `output[]` der Abfrageantwort heruntergeladen.
</Note>

## Unterstützte Modelle

| Anbieter | Modellname  | Merkmale                                                                                          |
| -------- | ----------- | ------------------------------------------------------------------------------------------------- |
| Tencent  | `hy-3d-3.1` | Hunyuan 3D 3.1, unterstützt Text-zu-3D, Bild-zu-3D und Skizze-zu-3D, optional mit PBR-Materialien |

**Generierungstypen (`generate_type`)**

| Typ        | Beschreibung                                                                          |
| :--------- | :------------------------------------------------------------------------------------ |
| `Normal`   | Standardgenerierung (Standard), Geometrie + Textur                                    |
| `Geometry` | Nur geometrisches Weißmodell ohne Textur                                              |
| `Sketch`   | Skizze-zu-3D, erlaubt die gleichzeitige Übergabe von Skizzenbild und Textbeschreibung |

## Detaillierte API-Beschreibung

### Request-Header

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

### 3D-Generierungsaufgabe erstellen

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

#### **Request-Body**

| Parameter          | Typ    | Pflicht | Beschreibung                                                                                                                                                                                                                                                                                          |
| :----------------- | :----- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model`            | string | Ja      | Modellname: `hy-3d-3.1`                                                                                                                                                                                                                                                                               |
| `prompt`           | string | Bedingt | Textbeschreibung, maximal 1024 Zeichen; mindestens einer der Parameter `prompt` oder `input_references` muss übergeben werden                                                                                                                                                                         |
| `input_references` | array  | Bedingt | Array von Referenzbildern (Bild-zu-3D), derzeit nur 1 Bild; pro Eintrag entweder `image_url` oder `image_base64`                                                                                                                                                                                      |
| `generate_type`    | string | Nein    | Generierungstyp: `Normal` (Standard) / `Geometry` / `Sketch`, Groß-/Kleinschreibung wird nicht unterschieden                                                                                                                                                                                          |
| `enable_pbr`       | bool   | Nein    | Ob PBR-Materialien generiert werden, Standard `false`                                                                                                                                                                                                                                                 |
| `face_count`       | int    | Nein    | Zielanzahl der Flächen, Bereich `3000`–`1500000`; ohne Angabe entscheidet das Modell                                                                                                                                                                                                                  |
| `format`           | string | Nein    | Ergebnisformat: `stl` / `usdz` / `fbx`, Groß-/Kleinschreibung wird nicht unterschieden; ohne Angabe gilt der Upstream-Standard (Normal liefert in der Regel obj + glb, Geometry nur glb); ein angegebenes Format wird **zusätzlich** generiert (z. B. liefert `format: "stl"` glb + stl, kein Ersatz) |
| `extra_body`       | object | Nein    | Durchreichen weiterer nativer Upstream-Parameter (siehe Beschreibung unten)                                                                                                                                                                                                                           |

**Validierungsregeln der Parameter**

* `prompt` und `input_references` schließen sich **gegenseitig aus** (nur einer darf übergeben werden); einzig bei `generate_type: "Sketch"` dürfen beide gleichzeitig übergeben werden (Skizze + Textbeschreibung).
* In jedem Eintrag von `input_references` muss **genau einer** der Parameter `image_url` oder `image_base64` übergeben werden:
  * `image_url` unterstützt nur öffentliche `http(s)`-URLs, **keine data-URLs** (verwenden Sie stattdessen `image_base64`);
  * `image_base64` darf dekodiert **6 MB** nicht überschreiten.
* `hy-3d-3.1` unterstützt den Generierungstyp `LowPoly` nicht.
* Die Gesamtgröße des Request-Bodys darf **10 MB** nicht überschreiten.

<Note>
  **Hinweise zur Verwendung von `extra_body`**: Native Upstream-Parameter (z. B. `polygon_type`) können auf der obersten Ebene von `extra_body` durchgereicht werden. Die folgenden Parameter **müssen als Top-Level-Felder** übergeben werden; erscheinen sie in `extra_body`, wird 400 zurückgegeben: `model`, `prompt`, `image_url`, `image_base64`, `generate_type`, `enable_pbr`, `face_count`, `result_format`; `multi_view_images` (Mehransichtsbilder) wird derzeit nicht unterstützt.
</Note>

#### Beispielantwort

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

#### Beschreibung der Statuswerte

| Status        | Beschreibung                                                                     |
| :------------ | :------------------------------------------------------------------------------- |
| `queued`      | In der Warteschlange                                                             |
| `in_progress` | Wird generiert                                                                   |
| `completed`   | Generierung abgeschlossen, `output` enthält die Download-Adressen der Ergebnisse |
| `failed`      | Generierung fehlgeschlagen, `error` enthält die Fehlerinformation                |

### Aufgabenstatus abfragen

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

Fragen Sie diese Schnittstelle ab, um zu prüfen, ob die Aufgabe abgeschlossen ist. Empfohlen wird eine Abfrage alle **10–15 Sekunden**. Die Abfrage wird nicht berechnet.

#### **Beispielantwort (Generierung abgeschlossen)**

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

**Beschreibung der Felder in `output[]`**

| Feld          | Beschreibung                                                                                                           |
| :------------ | :--------------------------------------------------------------------------------------------------------------------- |
| `type`        | Dateityp des Ergebnisses (kleingeschrieben), z. B. `obj`, `glb`, `stl`                                                 |
| `b64_json`    | Stets `null` (3D-Ergebnisse werden nicht inline zurückgegeben, sondern einheitlich über `content_url` heruntergeladen) |
| `content_url` | Download-Adresse des Ergebnisses (temporärer Upstream-Link), **bitte zeitnah herunterladen und umspeichern**           |
| `preview_url` | Adresse des Vorschaubilds (sofern vom Upstream bereitgestellt)                                                         |

<Warning>
  `content_url` und `preview_url` sind **temporäre Links** und laufen nach einiger Zeit ab. Bitte laden Sie die Dateien nach Abschluss der Aufgabe zeitnah herunter und speichern Sie sie in Ihrem eigenen Speicher. Die Aufgaben-ID ist ab Erstellung **24 Stunden** lang abfragbar (das Feld `expires_at` gibt den Abfrage-Stichtag an); nach Ablauf gibt die Abfrage einen Fehler zurück. Die temporären Links unterstützen nur GET-Anfragen; HEAD-Anfragen liefern den Status 403.
</Warning>

## Verwendungsbeispiele

<CodeGroup>
  ```shellscript Text-zu-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": "Ein Retro-Motorrad im Steampunk-Stil, Messingoptik, reich an Details",
      "enable_pbr": true
    }'
  ```

  ```shellscript Bild-zu-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 Bild-zu-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 Skizze-zu-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": "Ein Fluggerät im Science-Fiction-Stil mit Metallhülle",
      "input_references": [
        { "image_url": "https://example.com/sketch.png" }
      ]
    }'
  ```

  ```shellscript Flächenanzahl und Format angeben 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": "Ein mittelalterlicher Ritterhelm",
      "generate_type": "Normal",
      "enable_pbr": true,
      "face_count": 40000,
      "format": "fbx"
    }'
  ```
</CodeGroup>

## Vollständiges Aufrufbeispiel

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

  # Schritt 1: 3D-Generierungsaufgabe erstellen
  response = requests.post(
      f"{BASE_URL}/v1/3d/generations",
      headers=HEADERS,
      json={
          "model": "hy-3d-3.1",
          "prompt": "Ein Shiba Inu mit Hut",
          "enable_pbr": True
      }
  )
  result = response.json()
  generation_id = result["id"]
  print(f"Aufgabe erstellt, generation_id: {generation_id}")

  # Schritt 2: Status abfragen
  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"Aktueller Status: {current_status}")

      if current_status == "completed":
          print("3D-Generierung abgeschlossen!")
          break
      elif current_status == "failed":
          error = status_data.get("error") or {}
          print(f"Generierung fehlgeschlagen: {error.get('message', 'Unbekannter Fehler')}")
          exit(1)

      time.sleep(15)  # alle 15 Sekunden abfragen

  # Schritt 3: Ergebnisse herunterladen (content_url ist eine temporäre Adresse, direkter Download)
  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} gespeichert ({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() {
    // Schritt 1: Aufgabe erstellen
    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: "Ein Shiba Inu mit Hut",
        enable_pbr: true
      })
    });
    const { id: generationId } = await createResponse.json();
    console.log(`Aufgabe erstellt: ${generationId}`);

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

    if (result.status === "failed") {
      console.error(`Generierung fehlgeschlagen: ${result.error?.message}`);
      return;
    }

    // Schritt 3: Ergebnisse herunterladen
    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} gespeichert`);
    }
  }

  generate3D();
  ```
</CodeGroup>

## Abrechnung

* Abrechnung **pro Aufruf**: Der Preis ergibt sich aus der Kombination `Modell × generate_type × PBR aktiviert × Flächenanzahl angegeben × Format angegeben`; die konkreten Preise finden Sie in der [Modell-Galerie](https://aihubmix.com/models).
* Die Abrechnung erfolgt bei **erfolgreicher Erstellung der Aufgabe**; Statusabfrage und Download der Ergebnisse werden nicht berechnet.
* Parameterkombinationen ohne konfigurierten Preis werden bei der Erstellung direkt mit 400 abgelehnt, es entstehen keine Kosten.

## FAQ

### Wie lange dauert die 3D-Generierung?

In der Regel einige Minuten, abhängig von Modell, Generierungstyp und Flächenanzahl. Empfohlen wird ein Abfrageintervall von 10–15 Sekunden für die Abfrage-Schnittstelle.

### Wie lange sind Ergebnislinks und Aufgabe gültig?

* Die Aufgaben-ID ist ab Erstellung **24 Stunden** lang abfragbar; das Feld `expires_at` in der Antwort gibt den Abfrage-Stichtag an.
* `content_url` / `preview_url` sind temporäre Upstream-Links und laufen nach einiger Zeit ab. Bitte nach Abschluss der Aufgabe **zeitnah herunterladen und umspeichern**.

### Können `prompt` und Referenzbild gleichzeitig übergeben werden?

Nein, beide schließen sich gegenseitig aus — die einzige Ausnahme ist `generate_type: "Sketch"` (Skizze-zu-3D), bei dem Skizzenbild und Textbeschreibung gemeinsam übergeben werden dürfen.

### Worin unterscheiden sich die einzelnen `generate_type`-Typen?

| Typ        | Beschreibung                                           |
| :--------- | :----------------------------------------------------- |
| `Normal`   | Standardgenerierung (Geometrie + Textur), Standardwert |
| `Geometry` | Nur geometrisches Weißmodell, ohne Textur              |
| `Sketch`   | Skizze-zu-3D, Bild und Text gemeinsam möglich          |

### Was tun, wenn eine Aufgabe fehlschlägt?

Wenn `status` auf `failed` steht, enthält das Feld `error` in der Antwort die Fehlerinformation:

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

Häufige Fehlerursachen sind: Inhaltsverstoß, nicht unterstütztes Bildformat, nicht erreichbares Referenzbild usw. Bitte anhand der Fehlerinformation anpassen und erneut versuchen.

***

Zuletzt aktualisiert: 2026-07-17