# SDK-Integration

Verwende die offiziellen Tripo-SDKs, um eine Text-zu-Modell-Aufgabe zu übermitteln, auf ihren Abschluss zu warten, den Endstatus zu prüfen und das erzeugte Modell herunterzuladen. Die unten angegebenen Installationsquellen sind auf die Versionen festgelegt, mit denen diese Seite überprüft wurde.

## Unterstützte SDKs

| Sprache | API | Fixierte Version | Installationsquelle |
| --- | --- | --- | --- |
| JavaScript / TypeScript | V3 | [`e351348`](https://github.com/VAST-AI-Research/tripo-js-sdk/tree/e35134801b339caac0b84f36fe02d08e73e217b2) | Offizieller Git-Commit |
| Python | V2 + limited V3 | [`v0.4.2`](https://github.com/VAST-AI-Research/tripo-python-sdk/tree/v0.4.2) | PyPI `tripo3d==0.4.2` |
| Go | V3 | [`2c8c8d4`](https://github.com/VAST-AI-Research/tripo-go-sdk/tree/2c8c8d4e6a9e1fc9e49699fc055140eca689ee79) | Go-Pseudoversion `v0.0.0-20260713072120-2c8c8d4e6a9e` |
| Rust | V3 | [`f992f6a`](https://github.com/VAST-AI-Research/tripo-rust-sdk/tree/f992f6a7cf7a28c10781f9fa28e4630c7802291c) | Cargo-Git-Abhängigkeit |
| Java | V3 | [`7b6a68d`](https://github.com/VAST-AI-Research/tripo-java-sdk/tree/7b6a68d855e01a0b098775b1ee14ce7f3c8ac7d9) | Quellcode-Build; lokales Maven `0.1.0-SNAPSHOT` |

## 1. API-Schlüssel und Region konfigurieren

Erstelle einen Schlüssel in der [Tripo Console](https://platform.tripo3d.ai/) und stelle ihn ausschließlich deinem serverseitigen Prozess bereit. Verwende keinen API-Schlüssel im Browsercode und übertrage ihn nicht in die Versionsverwaltung.

```bash
export TRIPO_API_KEY="tsk_..."
```

JavaScript, Go und Rust verwenden weltweit `https://openapi.tripo3d.ai/v3` und in China `https://openapi.tripo3d.com/v3`. Java wählt `TripoRegion.GLOBAL` oder `TripoRegion.CN`; das SDK beginnt beim entsprechenden `.ai`- oder `.com`-Ursprung und hängt `/v3` an. Der Haupt-V2-Client von Python 0.4.2 verwendet weltweit `https://api.tripo3d.ai/v2/openapi` und in China `https://api.tripo3d.com/v2/openapi`; der begrenzte V3-Segmentierungsablauf verwendet zusätzlich den passenden Ursprung `https://openapi.tripo3d.ai` oder `.com`.

## 2. SDK installieren

Installiere jedes SDK aus seiner fixierten Produktionsquelle.

### JavaScript

```bash
npm install github:VAST-AI-Research/tripo-js-sdk#e35134801b339caac0b84f36fe02d08e73e217b2
```

### Python

```bash
python -m pip install tripo3d==0.4.2
```

### Go

```bash
go get github.com/VAST-AI-Research/tripo-go-sdk@v0.0.0-20260713072120-2c8c8d4e6a9e
```

### Rust

```toml
[dependencies]
tripo3d-sdk = { git = "https://github.com/VAST-AI-Research/tripo-rust-sdk.git", rev = "f992f6a7cf7a28c10781f9fa28e4630c7802291c" }
tokio = { version = "1", features = ["full"] }
anyhow = "1"
```

### Java

```bash
git clone https://github.com/VAST-AI-Research/tripo-java-sdk.git
cd tripo-java-sdk
git checkout 7b6a68d855e01a0b098775b1ee14ce7f3c8ac7d9
./mvnw install
```

Der Java-Build installiert `ai.tripo3d:tripo-sdk:0.1.0-SNAPSHOT` im lokalen Maven-Repository. Füge diese Koordinate deiner Anwendung hinzu, nachdem der Quellcode-Build abgeschlossen ist.

## 3. Senden, warten und herunterladen

Jedes serverseitige Beispiel liest `TRIPO_API_KEY`, übermittelt eine Text-zu-Modell-Aufgabe, wartet auf ein Endergebnis, prüft den Erfolg und speichert das primäre Modell sofort. Die URLs erzeugter Modelle sind temporär.

### JavaScript

```javascript
import { writeFile } from 'node:fs/promises';
import { TripoClient, ModelVersion, TaskStatus } from 'tripo3d-sdk-js';

const apiKey = process.env.TRIPO_API_KEY;
if (!apiKey) throw new Error('TRIPO_API_KEY is required');

const client = new TripoClient({
  apiKey,
  baseUrl: 'https://openapi.tripo3d.ai/v3',
});

const taskId = await client.textToModel({
  prompt: 'a cute red panda holding bamboo',
  model: ModelVersion.H3_1,
  texture: true,
  pbr: true,
  texture_quality: 'detailed',
});

const task = await client.waitForTask(taskId, {
  pollingIntervalMs: 2000,
  onProgress: (value) => console.log(`${value.status} — ${value.progress ?? 0}%`),
});

if (task.status !== TaskStatus.SUCCESS) {
  throw new Error(`Task did not succeed: ${task.status}`);
}

const modelUrl = task.output.model_url ?? task.output.model;
if (!modelUrl) throw new Error('Task returned no model URL');

const response = await fetch(modelUrl);
if (!response.ok) throw new Error(`Download failed: HTTP ${response.status}`);

await writeFile(`tripo-${taskId}.glb`, Buffer.from(await response.arrayBuffer()));
```

### Python

```python
import asyncio
import os
import shutil
from urllib.request import urlopen

from tripo3d import TripoClient
from tripo3d.models import TaskStatus


def download_file(url, path):
    with urlopen(url) as response, open(path, "wb") as output:
        shutil.copyfileobj(response, output)


async def main():
    api_key = os.environ["TRIPO_API_KEY"]
    os.makedirs("./output", exist_ok=True)

    async with TripoClient(api_key=api_key) as client:
        task_id = await client.text_to_model(
            prompt="a cute red panda holding bamboo",
            model_version="v2.5-20250123",
        )
        task = await client.wait_for_task(task_id, verbose=True)

        if task.status != TaskStatus.SUCCESS:
            raise RuntimeError(f"Task did not succeed: {task.status}")

        model_url = task.output.model
        if not model_url:
            raise RuntimeError("Task returned no model URL")

        output_path = "./output/model.glb"
        await asyncio.to_thread(download_file, model_url, output_path)
        print(f"Downloaded model: {output_path}")


asyncio.run(main())
```

### Go

```go
package main

import (
	"context"
	"fmt"
	"log"
	"os"
	"time"

	tripo3d "github.com/VAST-AI-Research/tripo-go-sdk"
)

func main() {
	apiKey := os.Getenv("TRIPO_API_KEY")
	if apiKey == "" {
		log.Fatal("TRIPO_API_KEY is required")
	}

	client, err := tripo3d.NewClient(tripo3d.ClientOptions{
		APIKey:  apiKey,
		BaseURL: "https://openapi.tripo3d.ai/v3",
	})
	if err != nil {
		log.Fatal(err)
	}

	ctx := context.Background()
	taskID, err := client.TextToModel(ctx, tripo3d.TextToModelParams{
		Prompt:         "a cute red panda holding bamboo",
		Model:          tripo3d.String(tripo3d.ModelVersionH31),
		Texture:        tripo3d.Bool(true),
		PBR:            tripo3d.Bool(true),
		TextureQuality: tripo3d.String("detailed"),
	})
	if err != nil {
		log.Fatal(err)
	}

	task, err := client.WaitForTask(ctx, taskID, tripo3d.WaitOptions{
		PollInterval: 2 * time.Second,
	})
	if err != nil {
		log.Fatal(err)
	}
	if task.Status != tripo3d.TaskStatusSuccess {
		log.Fatalf("Task did not succeed: %s", task.Status)
	}

	downloaded, err := client.DownloadModel(ctx, task)
	if err != nil {
		log.Fatal(err)
	}
	if downloaded == nil {
		log.Fatal("Task returned no model URL")
	}

	filename := fmt.Sprintf("tripo-%s.glb", taskID)
	if err := os.WriteFile(filename, downloaded.Data, 0o644); err != nil {
		log.Fatal(err)
	}
}
```

### Rust

```rust
use tokio::fs;
use tripo3d_sdk::{
    constants::model_version,
    params::TextToModelParams,
    ClientOptions,
    TaskStatus,
    TripoClient,
    WaitOptions,
};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let api_key = std::env::var("TRIPO_API_KEY")?;
    let client = TripoClient::new(ClientOptions {
        api_key: Some(api_key),
        base_url: Some("https://openapi.tripo3d.ai/v3".into()),
        ..Default::default()
    })?;

    let task_id = client
        .text_to_model(TextToModelParams {
            prompt: "a cute red panda holding bamboo".into(),
            model: Some(model_version::H3_1.to_string()),
            texture: Some(true),
            pbr: Some(true),
            texture_quality: Some("detailed".into()),
            ..Default::default()
        })
        .await?;

    let task = client
        .wait_for_task(&task_id, WaitOptions::default())
        .await?;
    if task.status != TaskStatus::Success {
        anyhow::bail!("Task did not succeed: {}", task.status);
    }

    let downloaded = client
        .download_model(&task)
        .await?
        .ok_or_else(|| anyhow::anyhow!("Task returned no model URL"))?;

    fs::write(format!("tripo-{task_id}.glb"), downloaded.data).await?;
    Ok(())
}
```

### Java

```java
import ai.tripo3d.sdk.api.TripoClient;
import ai.tripo3d.sdk.api.TripoClientConfig;
import ai.tripo3d.sdk.api.TripoRegion;
import ai.tripo3d.sdk.model.request.TaskRequestPayload;
import ai.tripo3d.sdk.model.response.TaskDetail;

import java.io.InputStream;
import java.net.URL;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.nio.file.StandardCopyOption;
import java.util.Map;

public final class TripoQuickStart {
    public static void main(String[] args) throws Exception {
        String apiKey = System.getenv("TRIPO_API_KEY");
        if (apiKey == null || apiKey.trim().isEmpty()) {
            throw new IllegalStateException("TRIPO_API_KEY is required");
        }

        try (TripoClient client = TripoClient.create(
                TripoClientConfig.builder(apiKey)
                        .region(TripoRegion.GLOBAL)
                        .build())) {
            TaskDetail created = client.textToModel(TaskRequestPayload.builder()
                    .prompt("a wooden chair")
                    .model("v3.1-20260211")
                    .build());

            TaskDetail done = client.pollUntilTerminal(created.taskId());
            if (!"success".equalsIgnoreCase(done.status())) {
                throw new IllegalStateException(
                        "Task failed: status=" + done.status()
                                + ", message=" + done.errorMsg());
            }

            Map<String, Object> output = done.output();
            Object modelUrl = output == null ? null : output.get("model_url");
            if (!(modelUrl instanceof String)) {
                throw new IllegalStateException(
                        "Task output does not contain model_url");
            }

            try (InputStream input =
                         new URL((String) modelUrl).openStream()) {
                Files.copy(
                        input,
                        Paths.get("model.glb"),
                        StandardCopyOption.REPLACE_EXISTING);
            }
        }
    }
}
```

JavaScript, Python und Java verwenden für die signierte Modell-URL bewusst native HTTP-Clients und fügen keinen `Authorization`-Header hinzu. Auch die Downloadmethoden der Go- und Rust-SDKs rufen die signierte URL ohne API-Schlüssel ab.

## 4. Unterstützung für V3-Routen

Die Matrix vereint alle fünf SDK-Implementierungen in den oben fixierten Versionen. Ein Häkchen bedeutet, dass ein öffentlicher SDK-Ablauf die endgültige V3-HTTP-Route direkt oder über einen internen Schritt erreicht; ungenutzte Routenkonstanten zählen nicht.

| HTTP-Route | Zweck | JavaScript | Python | Go | Rust | Java |
| --- | --- | :---: | :---: | :---: | :---: | :---: |
| `POST /v3/generation/text-to-model` | Modell aus Text erzeugen | ✓ | — | ✓ | ✓ | ✓ |
| `POST /v3/generation/image-to-model` | Modell aus einem Bild erzeugen | ✓ | — | ✓ | ✓ | ✓ |
| `POST /v3/generation/multiview-to-model` | Modell aus mehreren Ansichten erzeugen | ✓ | — | ✓ | ✓ | ✓ |
| `POST /v3/generation/text-to-image` | Bild aus Text erzeugen | ✓ | — | ✓ | ✓ | — |
| `POST /v3/generation/image-to-image` | Bild transformieren | ✓ | — | ✓ | ✓ | — |
| `POST /v3/generation/image-to-multiview` | Mehransichtsbilder erzeugen | ✓ | — | ✓ | ✓ | ✓ |
| `POST /v3/generation/edit-multiview` | Mehransichtsausgabe bearbeiten | ✓ | — | ✓ | ✓ | — |
| `POST /v3/generation/image-to-splat` | Gaussian Splat erzeugen | — | — | — | — | ✓ |
| `POST /v3/models/refine` | Entwurfsmodell verfeinern | — | — | — | — | ✓ |
| `POST /v3/models/texture` | Texturen anwenden oder neu erzeugen | ✓ | — | ✓ | ✓ | ✓ |
| `POST /v3/models/stylize` | Modell stilisieren | — | — | — | — | ✓ |
| `POST /v3/models/convert` | Modellformat konvertieren | ✓ | — | ✓ | ✓ | ✓ |
| `POST /v3/models/import` | Externes Modell importieren | — | — | — | — | ✓ |
| `POST /v3/mesh/segment` | Mesh segmentieren | ✓ | ✓ | ✓ | ✓ | ✓ |
| `POST /v3/mesh/complete` | Mesh vervollständigen oder reparieren | ✓ | — | ✓ | ✓ | ✓ |
| `POST /v3/mesh/decimate` | Flächenzahl reduzieren | ✓ | — | ✓ | ✓ | ✓ |
| `POST /v3/animations/rig-check` | Prüfen, ob ein Modell geriggt werden kann | ✓ | — | ✓ | ✓ | ✓ |
| `POST /v3/animations/rig` | Skelett anbringen | ✓ | — | ✓ | ✓ | ✓ |
| `POST /v3/animations/retarget` | Voreingestellte Animation anwenden | ✓ | — | ✓ | ✓ | ✓ |
| `GET /v3/tasks/{task_id}` | Eine Aufgabe abrufen | ✓ | ✓ | ✓ | ✓ | ✓ |
| `POST /v3/tasks/list` | Mehrere Aufgaben abrufen | ✓ | — | ✓ | ✓ | ✓ |
| `POST /v3/files` | Datei hochladen | ✓ | ✓ | ✓ | ✓ | ✓ |
| `POST /v3/files/presign` | Vorsignierten Upload erstellen | — | — | — | — | ✓ |
| `GET /v3/account/balance` | Kontostand abrufen | ✓ | — | ✓ | ✓ | ✓ |
| `GET /v3/account/usage` | Nutzungsverlauf abrufen | — | — | — | — | ✓ |

In dieser fixierten Version stellt nur Java image-to-splat, refine, stylize, import, presign und usage bereit. Java stellt text-to-image, image-to-image und edit-multiview nicht bereit. Der interne Deskriptor für `/v3/files/upload-credentials` besitzt weder einen Dienst noch eine öffentliche Clientmethode und wird daher nicht als unterstützt gezählt.

Python bleibt hauptsächlich ein V2-SDK. Der Zweig `mesh_segmentation(..., model_version="v2.0-20260430")` verwendet zusätzlich `POST /v3/mesh/segment`, `GET /v3/tasks/{task_id}` und `POST /v3/files`, wenn ein lokales `ref_image` hochgeladen werden muss.

### Unterstützung für Python-V2-Routen

Python 0.4.2 stellt fünf endgültige V2-HTTP-Routen bereit. `POST /v2/openapi/task` wird von den Methoden für Erzeugung, Modellverarbeitung, Mesh und Animation gemeinsam verwendet und ist nicht auf Text-zu-Modell beschränkt.

| HTTP-Route | Zweck |
| --- | --- |
| `POST /v2/openapi/task` | Jede unterstützte V2-Aufgabe übermitteln |
| `GET /v2/openapi/task/{task_id}` | Aufgabenstatus und Ausgabe abfragen |
| `GET /v2/openapi/user/balance` | Kontostand abrufen |
| `POST /v2/openapi/upload/sts/token` | STS-Upload-Anmeldedaten abrufen, wenn `boto3` verfügbar ist |
| `POST /v2/openapi/upload` | Datei über den älteren Multipart-Fallback des SDK hochladen |

Java und die anderen V3-SDKs senden die Modellauswahl über ihre offiziellen V3-Parametermodelle. Im Java-Wire-Format heißt das Feld `model`.

## 5. Fehlerbehebung

- **Fehlender Schlüssel:** Setze `TRIPO_API_KEY` im Serverprozess. Siehe [Authentifizierung](./authentication).
- **Falsche Region:** Wähle den passenden globalen oder chinesischen Endpunkt für das verwendete SDK und die verwendete API-Version.
- **Fehlgeschlagene Aufgabe oder Zeitüberschreitung:** Bewahre die `task_id` auf, prüfe den Endstatus und lies [Aufgabenlebenszyklus](./task-lifecycle) sowie [Fehlerbehandlung](./error-handling).
- **Abgelaufene Modell-URL:** Frage die Aufgabe erneut ab, wenn das SDK dies unterstützt, und lade das Modell dann sofort herunter. Speichere eine temporäre signierte URL nicht als dauerhaftes Asset.

## Offizielle Repositorys

- [JavaScript-SDK](https://github.com/VAST-AI-Research/tripo-js-sdk)
- [Python-SDK](https://github.com/VAST-AI-Research/tripo-python-sdk)
- [Go-SDK](https://github.com/VAST-AI-Research/tripo-go-sdk)
- [Rust-SDK](https://github.com/VAST-AI-Research/tripo-rust-sdk)
- [Java-SDK](https://github.com/VAST-AI-Research/tripo-java-sdk)