Интеграция SDK

Используйте официальные SDK Tripo, чтобы отправить задачу преобразования текста в модель, дождаться её завершения, проверить конечный статус и скачать созданную модель. Указанные ниже источники установки закреплены за версиями, на которых проверена эта страница.

Поддерживаемые SDK

Язык	API	Закреплённая версия	Источник установки
JavaScript / TypeScript	V3	`e351348`	Официальный Git commit
Python	V2 + limited V3	`v0.4.2`	PyPI `tripo3d==0.4.2`
Go	V3	`2c8c8d4`	Псевдоверсия Go `v0.0.0-20260713072120-2c8c8d4e6a9e`
Rust	V3	`f992f6a`	Зависимость Cargo из Git
Java	V3	`7b6a68d`	Сборка из исходников; локальный Maven `0.1.0-SNAPSHOT`

1. Настройка ключа API и региона

Создайте ключ в консоли Tripo и передавайте его только серверному процессу. Не помещайте ключ API в код браузера и не добавляйте его в систему контроля версий.

Bash

export TRIPO_API_KEY="tsk_..."

JavaScript, Go и Rust используют https://openapi.tripo3d.ai/v3 во всём мире и https://openapi.tripo3d.com/v3 в Китае. Java выбирает TripoRegion.GLOBAL или TripoRegion.CN; SDK начинает с соответствующего домена .ai или .com и добавляет /v3. Основной клиент V2 Python 0.4.2 использует https://api.tripo3d.ai/v2/openapi во всём мире и https://api.tripo3d.com/v2/openapi в Китае; ограниченный поток сегментации V3 также использует соответствующий домен https://openapi.tripo3d.ai или .com.

2. Установка SDK

Установите каждый SDK из закреплённого рабочего источника.

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 устанавливает ai.tripo3d:tripo-sdk:0.1.0-SNAPSHOT в локальный репозиторий Maven. После завершения сборки из исходников добавьте эти координаты в своё приложение.

3. Отправка, ожидание и скачивание

Каждый серверный пример считывает TRIPO_API_KEY, отправляет задачу преобразования текста в модель, ждёт конечного результата, проверяет успешность и сразу сохраняет основную модель. URL созданных моделей являются временными.

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 и Java намеренно используют нативные HTTP-клиенты для подписанного URL модели и не добавляют заголовок Authorization. Методы скачивания SDK для Go и Rust также получают подписанный URL без ключа API.

4. Поддержка маршрутов V3

Матрица объединяет реализации всех пяти SDK в закреплённых выше версиях. Галочка означает, что публичный поток SDK достигает конечного маршрута HTTP V3 напрямую или через внутренний шаг; неиспользуемые константы маршрутов не учитываются.

Маршрут HTTP	Назначение	JavaScript	Python	Go	Rust	Java
`POST /v3/generation/text-to-model`	Создать модель из текста	✓	—	✓	✓	✓
`POST /v3/generation/image-to-model`	Создать модель из одного изображения	✓	—	✓	✓	✓
`POST /v3/generation/multiview-to-model`	Создать модель по нескольким ракурсам	✓	—	✓	✓	✓
`POST /v3/generation/text-to-image`	Создать изображение из текста	✓	—	✓	✓	—
`POST /v3/generation/image-to-image`	Преобразовать изображение	✓	—	✓	✓	—
`POST /v3/generation/image-to-multiview`	Создать изображения с нескольких ракурсов	✓	—	✓	✓	✓
`POST /v3/generation/edit-multiview`	Изменить результат с несколькими ракурсами	✓	—	✓	✓	—
`POST /v3/generation/image-to-splat`	Создать Gaussian splat	—	—	—	—	✓
`POST /v3/models/refine`	Улучшить черновую модель	—	—	—	—	✓
`POST /v3/models/texture`	Наложить или повторно создать текстуры	✓	—	✓	✓	✓
`POST /v3/models/stylize`	Стилизовать модель	—	—	—	—	✓
`POST /v3/models/convert`	Преобразовать формат модели	✓	—	✓	✓	✓
`POST /v3/models/import`	Импортировать внешнюю модель	—	—	—	—	✓
`POST /v3/mesh/segment`	Сегментировать сетку	✓	✓	✓	✓	✓
`POST /v3/mesh/complete`	Дополнить или восстановить сетку	✓	—	✓	✓	✓
`POST /v3/mesh/decimate`	Уменьшить число граней	✓	—	✓	✓	✓
`POST /v3/animations/rig-check`	Проверить возможность привязки модели к скелету	✓	—	✓	✓	✓
`POST /v3/animations/rig`	Добавить скелет	✓	—	✓	✓	✓
`POST /v3/animations/retarget`	Применить готовую анимацию	✓	—	✓	✓	✓
`GET /v3/tasks/{task_id}`	Получить одну задачу	✓	✓	✓	✓	✓
`POST /v3/tasks/list`	Получить несколько задач	✓	—	✓	✓	✓
`POST /v3/files`	Загрузить файл	✓	✓	✓	✓	✓
`POST /v3/files/presign`	Создать предварительно подписанную загрузку	—	—	—	—	✓
`GET /v3/account/balance`	Получить баланс аккаунта	✓	—	✓	✓	✓
`GET /v3/account/usage`	Получить историю использования	—	—	—	—	✓

В этой закреплённой версии только Java предоставляет image-to-splat, refine, stylize, import, presign и usage. Java не предоставляет text-to-image, image-to-image и edit-multiview. Для внутреннего дескриптора /v3/files/upload-credentials нет ни сервиса, ни публичного метода клиента, поэтому он не считается поддерживаемым.

Python по-прежнему является преимущественно SDK V2. Ветка mesh_segmentation(..., model_version="v2.0-20260430") дополнительно использует POST /v3/mesh/segment, GET /v3/tasks/{task_id} и POST /v3/files, когда требуется загрузить локальный ref_image.

Поддержка маршрутов Python V2

Python 0.4.2 предоставляет пять конечных маршрутов HTTP V2. POST /v2/openapi/task совместно используется методами генерации, обработки моделей, сеток и анимации и не ограничивается преобразованием текста в модель.

Маршрут HTTP	Назначение
`POST /v2/openapi/task`	Отправить любую поддерживаемую задачу V2
`GET /v2/openapi/task/{task_id}`	Запросить статус и результат задачи
`GET /v2/openapi/user/balance`	Получить баланс аккаунта
`POST /v2/openapi/upload/sts/token`	Получить учётные данные STS, если доступен `boto3`
`POST /v2/openapi/upload`	Загрузить файл через устаревший multipart-резерв SDK

Java и другие SDK V3 передают выбор модели через официальные модели параметров V3. В передаваемых данных Java поле называется model.

5. Устранение неполадок

Нет ключа: задайте TRIPO_API_KEY в серверном процессе. См. раздел Аутентификация.
Неверный регион: выберите глобальную или китайскую конечную точку, соответствующую используемым SDK и версии API.
Ошибка или тайм-аут задачи: сохраните task_id, проверьте конечный статус и изучите разделы Жизненный цикл задачи и Обработка ошибок.
URL модели истёк: если SDK это поддерживает, запросите задачу повторно и сразу скачайте модель. Не храните временный подписанный URL как постоянный ресурс.

Интеграция SDK

Интеграция SDK

Поддерживаемые SDK

1. Настройка ключа API и региона

2. Установка SDK

3. Отправка, ожидание и скачивание

4. Поддержка маршрутов V3

Поддержка маршрутов Python V2

5. Устранение неполадок

Официальные репозитории