SDK Entegrasyonu

Resmi Tripo SDK’larını kullanarak bir text-to-model görevi gönderin, tamamlanmasını bekleyin, son durumu doğrulayın ve oluşturulan modeli indirin. Aşağıdaki kurulum kaynakları, bu sayfanın doğrulandığı sürümlere sabitlenmiştir.

Desteklenen SDK’lar

Dil	API	Sabit sürüm	Kurulum kaynağı
JavaScript / TypeScript	V3	`e351348`	Resmi Git commit’i
Python	V2 + limited V3	`v0.4.2`	PyPI `tripo3d==0.4.2`
Go	V3	`2c8c8d4`	Go pseudo-version `v0.0.0-20260713072120-2c8c8d4e6a9e`
Rust	V3	`f992f6a`	Cargo Git bağımlılığı
Java	V3	`7b6a68d`	Kaynak derleme; yerel Maven `0.1.0-SNAPSHOT`

1. API anahtarı ve bölgeyi yapılandırma

Tripo Console üzerinden bir anahtar oluşturun ve yalnızca sunucu tarafındaki işleme sağlayın. API anahtarını tarayıcı koduna koymayın veya kaynak kontrolüne göndermeyin.

Bash

export TRIPO_API_KEY="tsk_..."

JavaScript, Go ve Rust dünya genelinde https://openapi.tripo3d.ai/v3, Çin’de ise https://openapi.tripo3d.ai/v3 kullanır. Java, TripoRegion.GLOBAL veya TripoRegion.CN seçer; SDK ilgili .ai ya da .ai kaynağından başlar ve /v3 ekler. Python 0.4.2’nin ana V2 istemcisi dünya genelinde https://api.tripo3d.ai/v2/openapi, Çin’de ise https://api.tripo3d.ai/v2/openapi kullanır; sınırlı V3 segmentasyon akışı da karşılık gelen https://openapi.tripo3d.ai veya .ai kaynağını kullanır.

2. SDK’yı yükleme

Her SDK’yı sabitlenmiş üretim kaynağından yükleyin.

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

Java derlemesi, ai.tripo3d:tripo-sdk:0.1.0-SNAPSHOT koordinatını yerel Maven deposuna yükler. Kaynak derleme tamamlandıktan sonra bu koordinatı uygulamanıza ekleyin.

3. Gönderme, bekleme ve indirme

Sunucu tarafındaki her örnek TRIPO_API_KEY değerini okur, bir text-to-model görevi gönderir, son durumu bekler, başarıyı denetler ve ana modeli hemen kaydeder. Oluşturulan model URL’leri geçicidir.

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 ve Java, imzalı model URL’si için özellikle yerel HTTP istemcilerini kullanır ve Authorization başlığı eklemez. Go ve Rust SDK indirme yöntemleri de imzalı URL’yi API anahtarı olmadan getirir.

4. V3 rota desteği

Bu matris, yukarıdaki sabit sürümlerdeki beş SDK uygulamasının birleşimidir. Onay işareti, genel bir SDK akışının nihai V3 HTTP rotasına doğrudan veya dahili bir adımla ulaştığını gösterir; kullanılmayan rota sabitleri sayılmaz.

HTTP rotası	Amaç	JavaScript	Python	Go	Rust	Java
`POST /v3/generation/text-to-model`	Metinden model oluşturma	✓	—	✓	✓	✓
`POST /v3/generation/image-to-model`	Tek görüntüden model oluşturma	✓	—	✓	✓	✓
`POST /v3/generation/multiview-to-model`	Birden çok görünümden model oluşturma	✓	—	✓	✓	✓
`POST /v3/generation/text-to-image`	Metinden görüntü oluşturma	✓	—	✓	✓	—
`POST /v3/generation/image-to-image`	Görüntüyü dönüştürme	✓	—	✓	✓	—
`POST /v3/generation/image-to-multiview`	Çoklu görünüm görüntüleri oluşturma	✓	—	✓	✓	✓
`POST /v3/generation/edit-multiview`	Çoklu görünüm çıktısını düzenleme	✓	—	✓	✓	—
`POST /v3/generation/image-to-splat`	Gaussian splat oluşturma	—	—	—	—	✓
`POST /v3/models/refine`	Taslak modeli iyileştirme	—	—	—	—	✓
`POST /v3/models/texture`	Doku uygulama veya yeniden oluşturma	✓	—	✓	✓	✓
`POST /v3/models/stylize`	Modeli stilize etme	—	—	—	—	✓
`POST /v3/models/convert`	Model biçimini dönüştürme	✓	—	✓	✓	✓
`POST /v3/models/import`	Harici model içe aktarma	—	—	—	—	✓
`POST /v3/mesh/segment`	Ağı bölümlere ayırma	✓	✓	✓	✓	✓
`POST /v3/mesh/complete`	Ağı tamamlama veya onarma	✓	—	✓	✓	✓
`POST /v3/mesh/decimate`	Yüz sayısını azaltma	✓	—	✓	✓	✓
`POST /v3/animations/rig-check`	Modele rig uygulanıp uygulanamayacağını denetleme	✓	—	✓	✓	✓
`POST /v3/animations/rig`	İskelet ekleme	✓	—	✓	✓	✓
`POST /v3/animations/retarget`	Hazır animasyon uygulama	✓	—	✓	✓	✓
`GET /v3/tasks/{task_id}`	Tek bir görev alma	✓	✓	✓	✓	✓
`POST /v3/tasks/list`	Birden çok görev alma	✓	—	✓	✓	✓
`POST /v3/files`	Dosya yükleme	✓	✓	✓	✓	✓
`POST /v3/files/presign`	Önceden imzalanmış yükleme oluşturma	—	—	—	—	✓
`GET /v3/account/balance`	Hesap bakiyesini alma	✓	—	✓	✓	✓
`GET /v3/account/usage`	Kullanım geçmişini alma	—	—	—	—	✓

Bu sabit sürümde image-to-splat, refine, stylize, import, presign ve usage yalnızca Java tarafından sunulur. Java text-to-image, image-to-image veya edit-multiview sunmaz. /v3/files/upload-credentials dahili tanımlayıcısının karşılık gelen bir servisi veya genel istemci yöntemi yoktur, bu nedenle destekleniyor olarak sayılmaz.

Python hâlâ ağırlıklı olarak bir V2 SDK’sıdır. mesh_segmentation(..., model_version="v2.0-20260430") dalı ayrıca POST /v3/mesh/segment, GET /v3/tasks/{task_id} ve yerel bir ref_image yüklenmesi gerektiğinde POST /v3/files kullanır.

Python V2 rota desteği

Python 0.4.2 beş nihai V2 HTTP rotası sunar. POST /v2/openapi/task, üretim, model işleme, mesh ve animasyon görev yöntemleri tarafından paylaşılır; yalnızca text-to-model ile sınırlı değildir.

HTTP rotası	Amaç
`POST /v2/openapi/task`	Desteklenen herhangi bir V2 görevini gönderme
`GET /v2/openapi/task/{task_id}`	Görev durumunu ve çıktısını sorgulama
`GET /v2/openapi/user/balance`	Hesap bakiyesini alma
`POST /v2/openapi/upload/sts/token`	`boto3` kullanılabildiğinde STS yükleme kimlik bilgilerini alma
`POST /v2/openapi/upload`	SDK’nın eski multipart geri dönüşüyle dosya yükleme

Java ve diğer V3 SDK’ları model seçimini resmi V3 parametre modelleri üzerinden gönderir. Java aktarımında alan adı model şeklindedir.

5. Sorun giderme

Anahtar eksik: sunucu işleminde TRIPO_API_KEY değerini ayarlayın. Kimlik Doğrulama bölümüne bakın.
Yanlış bölge: kullanılan SDK ve API sürümüyle eşleşen küresel veya Çin uç noktasını seçin.
Başarısız veya zaman aşımına uğrayan görev: task_id değerini saklayın, son durumu inceleyin ve Görev Yaşam Döngüsü ile Hata İşleme bölümlerine bakın.
Model URL’sinin süresi doldu: SDK destekliyorsa görevi yeniden sorgulayın ve modeli hemen indirin. Geçici imzalı URL’yi kalıcı bir varlık olarak saklamayın.

SDK Entegrasyonu

SDK Entegrasyonu

Desteklenen SDK’lar

1. API anahtarı ve bölgeyi yapılandırma

2. SDK’yı yükleme

3. Gönderme, bekleme ve indirme

4. V3 rota desteği

Python V2 rota desteği

5. Sorun giderme

Resmi depolar