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`	Offizieller Git-Commit
Python	V2 + limited V3	`v0.4.2`	PyPI `tripo3d==0.4.2`
Go	V3	`2c8c8d4`	Go-Pseudoversion `v0.0.0-20260713072120-2c8c8d4e6a9e`
Rust	V3	`f992f6a`	Cargo-Git-Abhängigkeit
Java	V3	`7b6a68d`	Quellcode-Build; lokales Maven `0.1.0-SNAPSHOT`

1. API-Schlüssel und Region konfigurieren

Erstelle einen Schlüssel in der Tripo Console 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.

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

python -m pip install tripo3d==0.4.2

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

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

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.

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()));

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())

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

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(())
}

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.
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 sowie Fehlerbehandlung.
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.

SDK-Integration

SDK-Integration

Unterstützte SDKs

1. API-Schlüssel und Region konfigurieren

2. SDK installieren

3. Senden, warten und herunterladen

4. Unterstützung für V3-Routen

Unterstützung für Python-V2-Routen

5. Fehlerbehebung

Offizielle Repositorys