SDK 連携

Tripo 公式 SDK を使用して text-to-model タスクを送信し、完了を待ち、最終ステータスを確認して、生成されたモデルをダウンロードします。以下のインストール元は、このページの検証に使用したバージョンに固定されています。

対応 SDK

言語	API	固定バージョン	インストール元
JavaScript / TypeScript	V3	`e351348`	公式 Git コミット
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 を付加します。Python 0.4.2 のメイン V2 クライアントは、グローバルでは 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 を読み取り、text-to-model タスクを送信し、最終結果を待ち、成功を確認して、主モデルをすぐに保存します。生成されたモデルの 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 は、署名付きモデル URL にネイティブ HTTP クライアントを使用し、Authorization ヘッダーを付加しません。Go と Rust SDK のダウンロードメソッドも、API キーを付けずに署名付き URL を取得します。

4. V3 ルート対応状況

この表は、上記の固定バージョンにおける 5 つの SDK 実装の和集合です。チェックマークは、公開 SDK フローが最終的な V3 HTTP ルートへ直接または内部ステップ経由で到達することを示します。未使用のルート定数は数えません。

HTTP ルート	用途	JavaScript	Python	Go	Rust	Java
`POST /v3/generation/text-to-model`	テキストからモデルを生成	✓	—	✓	✓	✓
`POST /v3/generation/image-to-model`	1 枚の画像からモデルを生成	✓	—	✓	✓	✓
`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}`	1 件のタスクを取得	✓	✓	✓	✓	✓
`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 は引き続き主に V2 SDK です。mesh_segmentation(..., model_version="v2.0-20260430") の分岐では、さらに POST /v3/mesh/segment、GET /v3/tasks/{task_id}、ローカルの ref_image をアップロードする場合は POST /v3/files を使用します。

Python V2 ルート対応状況

Python 0.4.2 は 5 つの最終 V2 HTTP ルートを公開しています。POST /v2/openapi/task は生成、モデル処理、メッシュ、アニメーションの各タスクメソッドで共有され、text-to-model だけに限定されません。

HTTP ルート	用途
`POST /v2/openapi/task`	対応している任意の V2 タスクを送信
`GET /v2/openapi/task/{task_id}`	タスクのステータスと出力を照会
`GET /v2/openapi/user/balance`	アカウント残高を取得
`POST /v2/openapi/upload/sts/token`	`boto3` が利用可能な場合に STS アップロード認証情報を取得
`POST /v2/openapi/upload`	SDK のレガシー multipart フォールバックでファイルをアップロード

Java とその他の V3 SDK は、それぞれの公式 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. トラブルシューティング

公式リポジトリ