tripo3d

package module
v0.0.0-...-2c8c8d4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 13, 2026 License: MIT Imports: 15 Imported by: 0

README

tripo3d-sdk (Go)

English · 简体中文

The official Go SDK for the Tripo3D v3 API — a full AI 3D generation platform covering text-to-3D, image-to-3D, multiview-to-3D, re-texturing, mesh editing, auto-rigging and animation retargeting.

  • Zero third-party dependencies — built entirely on net/http and the standard library.
  • context.Context on every method for cancellation and deadlines.
  • Automatic retries on transient network / 5xx errors, honoring Retry-After.
  • Typed error values (*APIError, *TaskError, *TimeoutError, *RequestError) usable with errors.As.
  • WaitForTask poller with a progress callback.
  • Sibling SDK to tripo3d-sdk-js and tripo3d-sdk-rust — same API surface, idiomatic per language.

Base URL (global): https://openapi.tripo3d.ai/v3
Base URL (China): https://openapi.tripo3d.com/v3
This SDK targets the v3 REST API, not the older /v2/openapi/task endpoint.
Pass BaseURL to select your region (see Client options).

Installation

go get github.com/VAST-AI-Research/tripo-go-sdk

If the repository is private, configure Go to fetch it over SSH instead of HTTPS and mark it as private so go mod skips the public checksum database:

export GOPRIVATE=github.com/VAST-AI-Research/*
git config --global url."git@github.com:".insteadOf "https://github.com/"

For local development against a working copy of this repo, use a replace directive instead:

go mod edit -replace github.com/VAST-AI-Research/tripo-go-sdk=../tripo3d-sdk-go
go mod tidy

Create an API key on the Tripo console and export it (use platform.tripo3d.com in China):

export TRIPO_API_KEY="tsk_..."

Quick start

package main

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

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

func main() {
	client, err := tripo3d.NewClient(tripo3d.ClientOptions{
		// reads TRIPO_API_KEY
		BaseURL: "https://openapi.tripo3d.ai/v3", // use https://openapi.tripo3d.com/v3 in China
	})
	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,
		OnProgress: func(t *tripo3d.Task) {
			fmt.Printf("%s — %d%%\n", t.Status, t.Progress)
		},
	})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println("Model URL:", task.PrimaryModelURL())
}

⚠️ Model URLs expire ~5 minutes after task completion — download them right away. See client.DownloadModel(ctx, task).

Client options

tripo3d.NewClient(tripo3d.ClientOptions{
	APIKey:     "",           // defaults to TRIPO_API_KEY env var
	BaseURL:    "",           // global: https://openapi.tripo3d.ai/v3 · China: https://openapi.tripo3d.com/v3
	HTTPClient: nil,          // default: &http.Client{}
	Timeout:    0,            // per-request timeout, default 60s
	Retries:    0,            // extra attempts on 5xx / network errors; 0 = default (2), -1 = disabled
	UserAgent:  "",
})

API reference

Every generation method returns a task_id (string). Use WaitForTask to await the terminal result.

Generation
Method Endpoint Description
TextToModel(ctx, params) POST /generation/text-to-model Text → 3D model
ImageToModel(ctx, params) POST /generation/image-to-model Single image → 3D model
MultiviewToModel(ctx, params) POST /generation/multiview-to-model 4 views [front, left, back, right] → 3D model
TextToImage(ctx, params) POST /generation/text-to-image Concept image from text
ImageToImage(ctx, params) POST /generation/image-to-image Image style / edit
ImageToMultiview(ctx, params) POST /generation/image-to-multiview Image → 4-view sheet
EditMultiview(ctx, params) POST /generation/edit-multiview Refine multiview output
Model post-processing
Method Endpoint Description
TextureModel(ctx, params) POST /models/texture Re-texture an existing model
ConvertModel(ctx, params) POST /models/convert Convert to GLTF / FBX / OBJ / STL / USDZ / 3MF
SegmentMesh(ctx, params) POST /mesh/segment Semantic segmentation
CompleteMesh(ctx, params) POST /mesh/complete Mesh completion / repair
DecimateMesh(ctx, params) POST /mesh/decimate Retopology / face-count reduction
Animation
Method Endpoint Description
RigCheck(ctx, params) POST /animations/rig-check Detect whether a model is riggable
RigModel(ctx, params) POST /animations/rig Attach a skeleton
RetargetAnimation(ctx, params) POST /animations/retarget Apply preset animations
Utility
Method Endpoint Description
GetTask(ctx, taskID) GET /tasks/{task_id} Fetch a task snapshot
ListTasks(ctx, taskIDs) POST /tasks/list Batch task query
WaitForTask(ctx, taskID, opts) — Poll until terminal state
UploadFile(ctx, data, filename, contentType) POST /files Upload a raw file and get a file_token
GetBalance(ctx) GET /account/balance Account credit balance
DownloadModel(ctx, task) — Download the primary model URL into a []byte

Passing images / files

Any field of type FileDescriptor (or *FileDescriptor) can be built with tripo3d.File(...), which auto-detects URLs vs. bare file tokens:

f1 := tripo3d.File("https://example.com/hero.png")   // -> FileDescriptor{URL: "..."}
f2 := tripo3d.File("8f2a4c...")                       // -> FileDescriptor{FileToken: "..."}
f3 := tripo3d.FileDescriptor{Object: &tripo3d.ObjectRef{Bucket: "tripo-data", Key: "uploads/abc.png"}}

Upload a local buffer to get a file_token:

data, _ := os.ReadFile("./hero.png")
uploaded, err := client.UploadFile(ctx, data, "hero.png", "image/png")

taskID, err := client.ImageToModel(ctx, tripo3d.ImageToModelParams{
	File: tripo3d.File(uploaded.FileToken),
})
Optional fields and pointer helpers

Optional scalar fields are pointers (so the SDK can distinguish "not set" from the zero value). Use the tripo3d.Bool, tripo3d.String, tripo3d.Int64, and tripo3d.Float64 helpers to fill them:

tripo3d.TextToModelParams{
	Prompt:  "a cat",
	Texture: tripo3d.Bool(true),
	Model:   tripo3d.String(tripo3d.ModelVersionH31),
}

Every *Params struct also has an Extra map[string]interface{} field for forward-compatible passthrough of fields the SDK doesn't model yet.

End-to-end pipeline: game-ready character

// 1. Image -> 3D (low-poly P1 topology, mobile/game friendly)
modelID, _ := client.ImageToModel(ctx, tripo3d.ImageToModelParams{
	File:      tripo3d.File("https://example.com/hero.png"),
	Model:     tripo3d.String(tripo3d.ModelVersionP1),
	FaceLimit: tripo3d.Int64(5000),
	Texture:   tripo3d.Bool(true),
})
client.WaitForTask(ctx, modelID, tripo3d.WaitOptions{})

// 2. Verify skeleton compatibility
checkID, _ := client.RigCheck(ctx, tripo3d.RigCheckParams{Input: modelID})
check, _ := client.WaitForTask(ctx, checkID, tripo3d.WaitOptions{})
if !check.Output.IsRiggable() {
	log.Fatal("model is not riggable")
}

// 3. Attach skeleton (Mixamo-compatible bones -> Unity/Unreal ready)
rigID, _ := client.RigModel(ctx, tripo3d.RigModelParams{
	Input:   modelID,
	RigType: tripo3d.String(check.Output.RigType),
	Spec:    tripo3d.String(string(tripo3d.RigSpecMixamo)),
})
client.WaitForTask(ctx, rigID, tripo3d.WaitOptions{})

// 4. Bake preset locomotion animations
animID, _ := client.RetargetAnimation(ctx, tripo3d.RetargetAnimationParams{
	Input:      rigID,
	Animations: []string{string(tripo3d.AnimationIdle), string(tripo3d.AnimationWalk), string(tripo3d.AnimationRun)},
	OutFormat:  tripo3d.String(string(tripo3d.AnimOutFormatGLB)),
})
anim, _ := client.WaitForTask(ctx, animID, tripo3d.WaitOptions{})

fmt.Println("Animated GLB URLs:", anim.Output.ModelURLs)

Error handling

import "errors"

taskID, err := client.TextToModel(ctx, params)
if err != nil {
	var apiErr *tripo3d.APIError
	var reqErr *tripo3d.RequestError
	switch {
	case errors.As(err, &apiErr):
		log.Printf("API error %d: %s — %s", apiErr.Code, apiErr.Message, apiErr.Suggestion)
	case errors.As(err, &reqErr):
		log.Printf("transport failure: HTTP %d — %s", reqErr.StatusCode, reqErr.Body)
	default:
		log.Print(err)
	}
}

task, err := client.WaitForTask(ctx, taskID, tripo3d.WaitOptions{Timeout: 5 * time.Minute})
if err != nil {
	var taskErr *tripo3d.TaskError
	var timeoutErr *tripo3d.TimeoutError
	switch {
	case errors.As(err, &taskErr):
		log.Printf("task %s failed: %s", taskErr.Task.TaskID, taskErr.Task.ErrorMsg)
	case errors.As(err, &timeoutErr):
		log.Printf("gave up after %s — task %s", timeoutErr.Timeout, timeoutErr.TaskID)
	default:
		log.Print(err)
	}
}

Cancel a poll with context.WithTimeout / context.WithCancel — WaitForTask respects ctx.Done() on every iteration.

Constants

tripo3d.TaskStatusSuccess          // "success"
tripo3d.AnimationWalk              // "preset:walk"
tripo3d.RigTypeBiped               // "biped"
tripo3d.RigSpecMixamo              // "mixamo"
tripo3d.ModelVersionH31            // "v3.1-20260211"
tripo3d.ModelVersionP1             // "P1-20260311"
tripo3d.OutputFormatFBX            // "FBX"

Running the examples

export TRIPO_API_KEY="tsk_..."

go run ./examples/text-to-model "a wooden treasure chest"
go run ./examples/image-to-model ./hero.png
go run ./examples/rig-and-animate https://example.com/hero.png

Development

go build ./...
go vet ./...
go test ./...     # hermetic — uses httptest.Server, no real API key needed

Source tree:

client.go       # Client, NewClient, task/account/download methods
generation.go   # text/image/multiview -to-model + image generation params & methods
postprocess.go  # models/texture, models/convert, mesh/* params & methods
animation.go    # rig-check, rig, retarget params & methods
http.go         # net/http wrapper with retry + envelope parsing
errors.go       # APIError, RequestError, TaskError, TimeoutError
constants.go    # TaskStatus, Animation, RigType, RigSpec, ModelVersion, …
types.go        # Task, TaskOutput, Balance, FileDescriptor, …
helpers.go      # Bool/String/Int64/Float64 pointer helpers
examples/       # runnable end-to-end demos (one `main` package per example)
client_test.go  # httptest-backed unit tests

Reference

License

MIT — see LICENSE.

Documentation

Overview

Package tripo3d is the official Go SDK for the Tripo3D v3 API (https://developers.tripo3d.ai/en/docs/introduction) — an AI 3D generation platform covering text-to-3D, image-to-3D, multiview-to-3D, re-texturing, mesh editing, auto-rigging, and animation retargeting.

Global API base URL: https://openapi.tripo3d.ai/v3 China API base URL: https://openapi.tripo3d.com/v3 

client, err := tripo3d.NewClient(tripo3d.ClientOptions{}) // reads TRIPO_API_KEY
taskID, err := client.TextToModel(ctx, tripo3d.TextToModelParams{Prompt: "a cute cat"})
task, err := client.WaitForTask(ctx, taskID, tripo3d.WaitOptions{})
fmt.Println(task.PrimaryModelURL())

Index

Constants

View Source 
const (
	ModelVersionH31     = "v3.1-20260211"
	ModelVersionH30     = "v3.0-20250812"
	ModelVersionH25     = "v2.5-20250123"
	ModelVersionH20     = "v2.0-20240919"
	ModelVersionP1      = "P1-20260311"
	ModelVersionTurboV1 = "Turbo-v1.0-20250506"
)

ModelVersion lists the `model` values (product lines) exposed by the v3 API. Kept as plain strings (not a closed type) since Tripo3D regularly ships new model versions.

View Source 
const DefaultBaseURL = "https://openapi.tripo3d.com/v3"

DefaultBaseURL is the China mainland REST endpoint for the Tripo3D v3 openapi service. For overseas / global traffic use "https://openapi.tripo3d.ai/v3" via ClientOptions.BaseURL.

View Source 
const SDKVersion = "0.1.0"

SDKVersion is the current tripo3d-sdk-go release version, also used as part of the default User-Agent header.

Variables

This section is empty.

Functions

func Bool 

func Bool(v bool) *bool

Bool, Int64, Float64, and String return a pointer to the given value, for conveniently filling the optional (pointer-typed) fields of the various Params structs, e.g.: 

tripo3d.TextToModelParams{
    Prompt:  "a cute cat",
    Texture: tripo3d.Bool(true),
}

func Float64 

func Float64(v float64) *float64

func Int64 

func Int64(v int64) *int64

func String 

func String(v string) *string

Types

type APIError 

type APIError struct {
	Code       int
	Message    string
	Suggestion string
	StatusCode int
}

APIError is a well-formed `{ code, message, suggestion }` error envelope with a non-zero `code`, as returned by the Tripo3D API.

func (*APIError) Error 

func (e *APIError) Error() string

type AnimOutFormat 

type AnimOutFormat string

AnimOutFormat is the output format for rig / retarget tasks. 

const (
	AnimOutFormatGLB AnimOutFormat = "glb"
	AnimOutFormatFBX AnimOutFormat = "fbx"
)

type Animation 

type Animation string

Animation is a preset animation identifier accepted by POST /v3/animations/retarget. Combine at most 5 in a single call. 

const (
	AnimationIdle            Animation = "preset:idle"
	AnimationWalk            Animation = "preset:walk"
	AnimationRun             Animation = "preset:run"
	AnimationDive            Animation = "preset:dive"
	AnimationClimb           Animation = "preset:climb"
	AnimationJump            Animation = "preset:jump"
	AnimationSlash           Animation = "preset:slash"
	AnimationShoot           Animation = "preset:shoot"
	AnimationHurt            Animation = "preset:hurt"
	AnimationFall            Animation = "preset:fall"
	AnimationTurn            Animation = "preset:turn"
	AnimationQuadrupedWalk   Animation = "preset:quadruped:walk"
	AnimationHexapodWalk     Animation = "preset:hexapod:walk"
	AnimationOctopodWalk     Animation = "preset:octopod:walk"
	AnimationSerpentineMarch Animation = "preset:serpentine:march"
	AnimationAquaticMarch    Animation = "preset:aquatic:march"
)

type Balance 

type Balance struct {
	Balance float64 `json:"balance"`
	Frozen  float64 `json:"frozen,omitempty"`
}

Balance is the GET /v3/account/balance response payload.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is the entry point for the Tripo3D v3 API.

func NewClient 

func NewClient(opts ClientOptions) (*Client, error)

NewClient builds a Client, reading TRIPO_API_KEY from the environment when opts.APIKey is empty.

func (*Client) CompleteMesh 

func (c *Client) CompleteMesh(ctx context.Context, params CompleteMeshParams) (string, error)

CompleteMesh calls POST /v3/mesh/complete (mesh completion / repair) and returns the resulting task_id.

func (*Client) ConvertModel 

func (c *Client) ConvertModel(ctx context.Context, params ConvertModelParams) (string, error)

ConvertModel calls POST /v3/models/convert (convert a completed model to another format) and returns the resulting task_id.

func (*Client) DecimateMesh 

func (c *Client) DecimateMesh(ctx context.Context, params DecimateMeshParams) (string, error)

DecimateMesh calls POST /v3/mesh/decimate (retopology / face-count reduction) and returns the resulting task_id.

func (*Client) DownloadModel 

func (c *Client) DownloadModel(ctx context.Context, task *Task) (*DownloadedModel, error)

DownloadModel fetches the primary model URL of a completed task. Returns (nil, nil) when the task has no model output.

func (*Client) EditMultiview 

func (c *Client) EditMultiview(ctx context.Context, params EditMultiviewParams) (string, error)

EditMultiview calls POST /v3/generation/edit-multiview (refine a previously generated multiview set) and returns the resulting task_id.

func (*Client) GetBalance 

func (c *Client) GetBalance(ctx context.Context) (*Balance, error)

GetBalance calls GET /v3/account/balance.

func (*Client) GetTask 

func (c *Client) GetTask(ctx context.Context, taskID string) (*Task, error)

GetTask calls GET /v3/tasks/{task_id}.

func (*Client) ImageToImage 

func (c *Client) ImageToImage(ctx context.Context, params ImageToImageParams) (string, error)

ImageToImage calls POST /v3/generation/image-to-image (image style / edit transformation) and returns the resulting task_id.

func (*Client) ImageToModel 

func (c *Client) ImageToModel(ctx context.Context, params ImageToModelParams) (string, error)

ImageToModel calls POST /v3/generation/image-to-model and returns the resulting task_id.

func (*Client) ImageToMultiview 

func (c *Client) ImageToMultiview(ctx context.Context, params ImageToMultiviewParams) (string, error)

ImageToMultiview calls POST /v3/generation/image-to-multiview and returns the resulting task_id.

func (*Client) ListTasks 

func (c *Client) ListTasks(ctx context.Context, taskIDs []string) ([]Task, error)

ListTasks calls POST /v3/tasks/list to batch-query multiple tasks in one round trip.

func (*Client) MultiviewToModel 

func (c *Client) MultiviewToModel(ctx context.Context, params MultiviewToModelParams) (string, error)

MultiviewToModel calls POST /v3/generation/multiview-to-model and returns the resulting task_id.

func (*Client) RetargetAnimation 

func (c *Client) RetargetAnimation(ctx context.Context, params RetargetAnimationParams) (string, error)

RetargetAnimation calls POST /v3/animations/retarget (apply preset animations to a rigged model) and returns the resulting task_id.

func (*Client) RigCheck 

func (c *Client) RigCheck(ctx context.Context, params RigCheckParams) (string, error)

RigCheck calls POST /v3/animations/rig-check, which determines whether a generated model can be rigged and (if so) the recommended skeleton type. It returns the resulting task_id.

func (*Client) RigModel 

func (c *Client) RigModel(ctx context.Context, params RigModelParams) (string, error)

RigModel calls POST /v3/animations/rig (attach a skeleton to a model) and returns the resulting task_id.

func (*Client) SegmentMesh 

func (c *Client) SegmentMesh(ctx context.Context, params SegmentMeshParams) (string, error)

SegmentMesh calls POST /v3/mesh/segment (semantic segmentation of a mesh) and returns the resulting task_id.

func (*Client) TextToImage 

func (c *Client) TextToImage(ctx context.Context, params TextToImageParams) (string, error)

TextToImage calls POST /v3/generation/text-to-image and returns the resulting task_id.

func (*Client) TextToModel 

func (c *Client) TextToModel(ctx context.Context, params TextToModelParams) (string, error)

TextToModel calls POST /v3/generation/text-to-model and returns the resulting task_id.

func (*Client) TextureModel 

func (c *Client) TextureModel(ctx context.Context, params TextureModelParams) (string, error)

TextureModel calls POST /v3/models/texture (re-texture an existing model) and returns the resulting task_id.

func (*Client) UploadFile 

func (c *Client) UploadFile(ctx context.Context, data []byte, filename, contentType string) (*UploadedFile, error)

UploadFile calls POST /v3/files, uploading a raw file and returning its file_token.

func (*Client) WaitForTask 

func (c *Client) WaitForTask(ctx context.Context, taskID string, opts WaitOptions) (*Task, error)

WaitForTask polls GET /v3/tasks/{task_id} until the task reaches a terminal state, or the context is cancelled / opts.Timeout elapses.

By default, a non-"success" terminal status is surfaced as a *TaskError; set opts.IgnoreFailure to receive the task without an error instead.

type ClientOptions 

type ClientOptions struct {
	// APIKey authenticates requests. Falls back to the TRIPO_API_KEY
	// environment variable when empty.
	APIKey string
	// BaseURL overrides the API endpoint. Defaults to DefaultBaseURL.
	BaseURL string
	// HTTPClient overrides the underlying *http.Client. Defaults to
	// http.DefaultClient's zero value (a fresh client with no timeout of
	// its own — per-request timeouts are enforced via Timeout instead).
	HTTPClient *http.Client
	// Timeout bounds each individual HTTP request (not the whole
	// WaitForTask polling loop). Defaults to 60s.
	Timeout time.Duration
	// Retries is the number of extra attempts made on transient network
	// errors or 5xx/429 responses. Defaults to 2.
	//
	// Quirk: because Go's zero value for int is 0, and 0 is also a
	// perfectly valid "use the default" sentinel here, pass -1 to
	// explicitly disable retries.
	Retries int
	// UserAgent overrides the default "tripo3d-sdk-go/<version>" header.
	UserAgent string
}

ClientOptions configures a Client. All fields are optional; APIKey falls back to the TRIPO_API_KEY environment variable when unset.

type CompleteMeshParams 

type CompleteMeshParams struct {
	Input     string   `json:"input"`
	Model     *string  `json:"model,omitempty"`
	PartNames []string `json:"part_names,omitempty"`

	Extra map[string]interface{} `json:"-"`
}

CompleteMeshParams are the parameters for POST /v3/mesh/complete.

type ConvertModelParams 

type ConvertModelParams struct {
	Input                  string   `json:"input"`
	Format                 string   `json:"format"`
	Quad                   *bool    `json:"quad,omitempty"`
	FaceLimit              *int64   `json:"face_limit,omitempty"`
	TextureSize            *int64   `json:"texture_size,omitempty"`
	TextureFormat          *string  `json:"texture_format,omitempty"`
	FlattenBottom          *bool    `json:"flatten_bottom,omitempty"`
	FlattenBottomThreshold *float64 `json:"flatten_bottom_threshold,omitempty"`
	PivotToCenterBottom    *bool    `json:"pivot_to_center_bottom,omitempty"`
	WithAnimation          *bool    `json:"with_animation,omitempty"`
	PackUV                 *bool    `json:"pack_uv,omitempty"`
	ForceSymmetry          *bool    `json:"force_symmetry,omitempty"`
	Bake                   *bool    `json:"bake,omitempty"`
	PartNames              []string `json:"part_names,omitempty"`

	Extra map[string]interface{} `json:"-"`
}

ConvertModelParams are the parameters for POST /v3/models/convert.

type DecimateMeshParams 

type DecimateMeshParams struct {
	Input     string   `json:"input"`
	Model     *string  `json:"model,omitempty"`
	FaceLimit *int64   `json:"face_limit,omitempty"`
	Quad      *bool    `json:"quad,omitempty"`
	Bake      *bool    `json:"bake,omitempty"`
	PartNames []string `json:"part_names,omitempty"`

	Extra map[string]interface{} `json:"-"`
}

DecimateMeshParams are the parameters for POST /v3/mesh/decimate.

type DownloadedModel 

type DownloadedModel struct {
	URL         string
	ContentType string
	Data        []byte
}

DownloadedModel is the result of Client.DownloadModel.

type EditMultiviewParams 

type EditMultiviewParams struct {
	OriginalTaskID *string `json:"original_task_id,omitempty"`

	Extra map[string]interface{} `json:"-"`
}

EditMultiviewParams are the parameters for POST /v3/generation/edit-multiview.

type FileDescriptor 

type FileDescriptor struct {
	FileToken string     `json:"file_token,omitempty"`
	URL       string     `json:"url,omitempty"`
	Object    *ObjectRef `json:"object,omitempty"`
	Type      string     `json:"type,omitempty"`
}

FileDescriptor is the shape accepted by every endpoint that takes an image or model file as input. Exactly one of FileToken, URL, or Object should normally be set.

func File 

func File(input string) FileDescriptor

File builds a FileDescriptor from a bare string: an absolute URL (http:// or https://) is stored as URL, anything else is treated as an already-uploaded file_token.

func (FileDescriptor) IsEmpty 

func (f FileDescriptor) IsEmpty() bool

IsEmpty reports whether none of the descriptor's fields are populated.

type ImageToImageParams 

type ImageToImageParams struct {
	File   *FileDescriptor `json:"file,omitempty"`
	Prompt *string         `json:"prompt,omitempty"`

	Extra map[string]interface{} `json:"-"`
}

ImageToImageParams are the parameters for POST /v3/generation/image-to-image.

type ImageToModelParams 

type ImageToModelParams struct {
	File               FileDescriptor `json:"file"`
	Model              *string        `json:"model,omitempty"`
	EnableImageAutofix *bool          `json:"enable_image_autofix,omitempty"`
	ModelSeed          *int64         `json:"model_seed,omitempty"`
	TextureSeed        *int64         `json:"texture_seed,omitempty"`
	Texture            *bool          `json:"texture,omitempty"`
	PBR                *bool          `json:"pbr,omitempty"`
	TextureQuality     *string        `json:"texture_quality,omitempty"`
	TextureAlignment   *string        `json:"texture_alignment,omitempty"`
	GeometryQuality    *string        `json:"geometry_quality,omitempty"`
	FaceLimit          *int64         `json:"face_limit,omitempty"`
	AutoSize           *bool          `json:"auto_size,omitempty"`
	Orientation        *string        `json:"orientation,omitempty"`
	Quad               *bool          `json:"quad,omitempty"`
	SmartLowPoly       *bool          `json:"smart_low_poly,omitempty"`
	GenerateParts      *bool          `json:"generate_parts,omitempty"`
	Compress           *string        `json:"compress,omitempty"`
	ExportUV           *bool          `json:"export_uv,omitempty"`
	Style              *string        `json:"style,omitempty"`

	Extra map[string]interface{} `json:"-"`
}

ImageToModelParams are the parameters for POST /v3/generation/image-to-model.

type ImageToMultiviewParams 

type ImageToMultiviewParams struct {
	File *FileDescriptor `json:"file,omitempty"`

	Extra map[string]interface{} `json:"-"`
}

ImageToMultiviewParams are the parameters for POST /v3/generation/image-to-multiview.

type MultiviewToModelParams 

type MultiviewToModelParams struct {
	Files            *[4]FileDescriptor `json:"files,omitempty"`
	OriginalTaskID   *string            `json:"original_task_id,omitempty"`
	Model            *string            `json:"model,omitempty"`
	ModelSeed        *int64             `json:"model_seed,omitempty"`
	TextureSeed      *int64             `json:"texture_seed,omitempty"`
	Texture          *bool              `json:"texture,omitempty"`
	PBR              *bool              `json:"pbr,omitempty"`
	TextureQuality   *string            `json:"texture_quality,omitempty"`
	TextureAlignment *string            `json:"texture_alignment,omitempty"`
	FaceLimit        *int64             `json:"face_limit,omitempty"`
	AutoSize         *bool              `json:"auto_size,omitempty"`
	Orientation      *string            `json:"orientation,omitempty"`
	Quad             *bool              `json:"quad,omitempty"`
	SmartLowPoly     *bool              `json:"smart_low_poly,omitempty"`
	GenerateParts    *bool              `json:"generate_parts,omitempty"`
	Compress         *string            `json:"compress,omitempty"`

	Extra map[string]interface{} `json:"-"`
}

MultiviewToModelParams are the parameters for POST /v3/generation/multiview-to-model.

Files, when set, must contain exactly 4 items in [front, left, back, right] order. Individual items may be a zero-value FileDescriptor (empty) except the front view. Mutually exclusive with OriginalTaskID.

type ObjectRef 

type ObjectRef struct {
	Bucket string `json:"bucket"`
	Key    string `json:"key"`
}

ObjectRef is a bucket/key pair for pre-uploaded assets (STS-style upload).

type OutputFormat 

type OutputFormat string

OutputFormat is a model conversion output format accepted by POST /v3/models/convert. 

const (
	OutputFormatGLTF    OutputFormat = "GLTF"
	OutputFormatGLB     OutputFormat = "GLB"
	OutputFormatUSDZ    OutputFormat = "USDZ"
	OutputFormatFBX     OutputFormat = "FBX"
	OutputFormatOBJ     OutputFormat = "OBJ"
	OutputFormatSTL     OutputFormat = "STL"
	OutputFormatThreeMF OutputFormat = "3MF"
)

type RequestError 

type RequestError struct {
	Message    string
	StatusCode int
	Body       string
	Err        error
}

RequestError is a transport-level failure: a network error, a non-2xx status without a parseable error envelope, or a malformed response body.

func (*RequestError) Error 

func (e *RequestError) Error() string

func (*RequestError) Unwrap 

func (e *RequestError) Unwrap() error

type RetargetAnimationParams 

type RetargetAnimationParams struct {
	Input              string   `json:"input"`
	Animation          *string  `json:"animation,omitempty"`
	Animations         []string `json:"animations,omitempty"`
	OutFormat          *string  `json:"out_format,omitempty"`
	BakeAnimation      *bool    `json:"bake_animation,omitempty"`
	ExportWithGeometry *bool    `json:"export_with_geometry,omitempty"`
	AnimateInPlace     *bool    `json:"animate_in_place,omitempty"`

	Extra map[string]interface{} `json:"-"`
}

RetargetAnimationParams are the parameters for POST /v3/animations/retarget. Provide either Animation (single preset) or Animations (up to 5).

type RigCheckParams 

type RigCheckParams struct {
	Input string `json:"input"`

	Extra map[string]interface{} `json:"-"`
}

RigCheckParams are the parameters for POST /v3/animations/rig-check.

type RigModelParams 

type RigModelParams struct {
	Input     string  `json:"input"`
	RigType   *string `json:"rig_type,omitempty"`
	Spec      *string `json:"spec,omitempty"`
	OutFormat *string `json:"out_format,omitempty"`

	Extra map[string]interface{} `json:"-"`
}

RigModelParams are the parameters for POST /v3/animations/rig.

type RigSpec 

type RigSpec string

RigSpec controls bone naming/hierarchy conventions. 

const (
	RigSpecMixamo RigSpec = "mixamo"
	RigSpecTripo  RigSpec = "tripo"
)

type RigType 

type RigType string

RigType is a skeleton topology for POST /v3/animations/rig. 

const (
	RigTypeBiped      RigType = "biped"
	RigTypeQuadruped  RigType = "quadruped"
	RigTypeHexapod    RigType = "hexapod"
	RigTypeOctopod    RigType = "octopod"
	RigTypeAvian      RigType = "avian"
	RigTypeSerpentine RigType = "serpentine"
	RigTypeAquatic    RigType = "aquatic"
	RigTypeOthers     RigType = "others"
)

type SegmentMeshParams 

type SegmentMeshParams struct {
	Input string  `json:"input"`
	Model *string `json:"model,omitempty"`

	Extra map[string]interface{} `json:"-"`
}

SegmentMeshParams are the parameters for POST /v3/mesh/segment.

type Task 

type Task struct {
	TaskID          string          `json:"task_id"`
	Type            string          `json:"type"`
	Status          TaskStatus      `json:"status"`
	Progress        int             `json:"progress,omitempty"`
	Input           json.RawMessage `json:"input,omitempty"`
	Output          *TaskOutput     `json:"output,omitempty"`
	CreateTime      int64           `json:"create_time,omitempty"`
	RunningLeftTime int64           `json:"running_left_time,omitempty"`
	QueuingNum      int64           `json:"queuing_num,omitempty"`
	ErrorCode       int64           `json:"error_code,omitempty"`
	ErrorMsg        string          `json:"error_msg,omitempty"`

	// Raw holds the complete, unparsed JSON object for this task, so callers
	// can reach fields this struct doesn't model yet.
	Raw json.RawMessage `json:"-"`
}

Task is a task snapshot as returned by GET /v3/tasks/{task_id} and POST /v3/tasks/list.

func (*Task) PrimaryModelURL 

func (t *Task) PrimaryModelURL() string

PrimaryModelURL returns the best-effort "main" model URL for this task, checking the common output fields in priority order. Returns "" if the task has no model output.

func (*Task) UnmarshalJSON 

func (t *Task) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes the known fields while also retaining the full raw payload in Raw, so newly added API fields remain accessible.

type TaskError 

type TaskError struct {
	Task *Task
}

TaskError indicates a task reached a non-successful terminal state (failed / cancelled / banned / expired).

func (*TaskError) Error 

func (e *TaskError) Error() string

type TaskOutput 

type TaskOutput struct {
	Model            string   `json:"model,omitempty"`
	ModelURL         string   `json:"model_url,omitempty"`
	ModelURLs        []string `json:"model_urls,omitempty"`
	BaseModel        string   `json:"base_model,omitempty"`
	PBRModel         string   `json:"pbr_model,omitempty"`
	RenderedImage    string   `json:"rendered_image,omitempty"`
	RenderedImageURL string   `json:"rendered_image_url,omitempty"`
	Riggable         *bool    `json:"riggable,omitempty"`
	RigType          string   `json:"rig_type,omitempty"`

	// Raw holds the complete, unparsed JSON object for this output.
	Raw json.RawMessage `json:"-"`
}

TaskOutput is the `output` object of a completed task. Fields vary by task type, so everything is optional.

func (*TaskOutput) IsRiggable 

func (o *TaskOutput) IsRiggable() bool

IsRiggable reports the rig-check verdict, defaulting to false when unset.

func (*TaskOutput) PrimaryModelURL 

func (o *TaskOutput) PrimaryModelURL() string

PrimaryModelURL returns the best-effort "main" model URL, checking the common output fields in priority order. Safe to call on a nil receiver.

func (*TaskOutput) UnmarshalJSON 

func (o *TaskOutput) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes the known fields while also retaining the full raw payload in Raw.

type TaskStatus 

type TaskStatus string

TaskStatus is the lifecycle status of a task, as returned by GET /v3/tasks/{task_id}. 

const (
	TaskStatusQueued    TaskStatus = "queued"
	TaskStatusRunning   TaskStatus = "running"
	TaskStatusSuccess   TaskStatus = "success"
	TaskStatusFailed    TaskStatus = "failed"
	TaskStatusCancelled TaskStatus = "cancelled"
	TaskStatusUnknown   TaskStatus = "unknown"
	TaskStatusBanned    TaskStatus = "banned"
	TaskStatusExpired   TaskStatus = "expired"
)

func (TaskStatus) IsSuccess 

func (s TaskStatus) IsSuccess() bool

IsSuccess reports whether this status represents a successful completion.

func (TaskStatus) IsTerminal 

func (s TaskStatus) IsTerminal() bool

IsTerminal reports whether a task in this status will not change further.

type TextToImageParams 

type TextToImageParams struct {
	Prompt string  `json:"prompt"`
	Model  *string `json:"model,omitempty"`

	Extra map[string]interface{} `json:"-"`
}

TextToImageParams are the parameters for POST /v3/generation/text-to-image.

type TextToModelParams 

type TextToModelParams struct {
	Prompt          string  `json:"prompt"`
	Model           *string `json:"model,omitempty"`
	NegativePrompt  *string `json:"negative_prompt,omitempty"`
	ImageSeed       *int64  `json:"image_seed,omitempty"`
	ModelSeed       *int64  `json:"model_seed,omitempty"`
	TextureSeed     *int64  `json:"texture_seed,omitempty"`
	Texture         *bool   `json:"texture,omitempty"`
	PBR             *bool   `json:"pbr,omitempty"`
	TextureQuality  *string `json:"texture_quality,omitempty"`
	GeometryQuality *string `json:"geometry_quality,omitempty"`
	FaceLimit       *int64  `json:"face_limit,omitempty"`
	AutoSize        *bool   `json:"auto_size,omitempty"`
	Quad            *bool   `json:"quad,omitempty"`
	SmartLowPoly    *bool   `json:"smart_low_poly,omitempty"`
	GenerateParts   *bool   `json:"generate_parts,omitempty"`
	Compress        *string `json:"compress,omitempty"`
	ExportUV        *bool   `json:"export_uv,omitempty"`
	Style           *string `json:"style,omitempty"`

	// Extra carries forward-compatible fields not yet modeled above; they
	// are merged into the JSON payload alongside the typed fields.
	Extra map[string]interface{} `json:"-"`
}

TextToModelParams are the parameters for POST /v3/generation/text-to-model.

type TextureFormat 

type TextureFormat string

TextureFormat is a texture image format supported by the conversion API. 

const (
	TextureFormatBMP     TextureFormat = "BMP"
	TextureFormatDPX     TextureFormat = "DPX"
	TextureFormatHDR     TextureFormat = "HDR"
	TextureFormatJPEG    TextureFormat = "JPEG"
	TextureFormatOpenEXR TextureFormat = "OPEN_EXR"
	TextureFormatPNG     TextureFormat = "PNG"
	TextureFormatTarga   TextureFormat = "TARGA"
	TextureFormatTIFF    TextureFormat = "TIFF"
	TextureFormatWebP    TextureFormat = "WEBP"
)

type TextureModelParams 

type TextureModelParams struct {
	Input            string          `json:"input"`
	Texture          *bool           `json:"texture,omitempty"`
	PBR              *bool           `json:"pbr,omitempty"`
	ModelSeed        *int64          `json:"model_seed,omitempty"`
	TextureSeed      *int64          `json:"texture_seed,omitempty"`
	TextureQuality   *string         `json:"texture_quality,omitempty"`
	TextureAlignment *string         `json:"texture_alignment,omitempty"`
	TextPrompt       *string         `json:"text_prompt,omitempty"`
	ImagePrompt      *FileDescriptor `json:"image_prompt,omitempty"`
	StyleImage       *FileDescriptor `json:"style_image,omitempty"`
	Compress         *string         `json:"compress,omitempty"`
	Bake             *bool           `json:"bake,omitempty"`
	PartNames        []string        `json:"part_names,omitempty"`

	Extra map[string]interface{} `json:"-"`
}

TextureModelParams are the parameters for POST /v3/models/texture.

type TimeoutError 

type TimeoutError struct {
	TaskID  string
	Timeout time.Duration
}

TimeoutError indicates WaitForTask exceeded the caller-supplied timeout.

func (*TimeoutError) Error 

func (e *TimeoutError) Error() string

type UploadedFile 

type UploadedFile struct {
	FileToken string `json:"file_token"`
}

UploadedFile is the POST /v3/files response payload.

type WaitOptions 

type WaitOptions struct {
	// PollInterval is the delay between polling attempts. Defaults to 2s.
	PollInterval time.Duration
	// Timeout bounds the overall polling loop. Zero means wait
	// indefinitely (until ctx is cancelled).
	Timeout time.Duration
	// IgnoreFailure, when true, returns the task even if its terminal
	// status isn't "success", instead of returning a *TaskError.
	IgnoreFailure bool
	// OnProgress, if set, is invoked after every poll (including the
	// final one) with the latest task snapshot.
	OnProgress func(*Task)
}

WaitOptions configures Client.WaitForTask.

Source Files

View all Source files

Directories

Path Synopsis
examples
image-to-image command
Command image-to-image applies a style/edit transformation to an existing image and saves the result to disk.
 Command image-to-image applies a style/edit transformation to an existing image and saves the result to disk.
image-to-model command
Command image-to-model converts a local or remote image into a 3D model.
 Command image-to-model converts a local or remote image into a 3D model.
rig-and-animate command
Command rig-and-animate runs an end-to-end "game-ready character" pipeline:
 Command rig-and-animate runs an end-to-end "game-ready character" pipeline:
text-to-image command
Command text-to-image generates a concept image from a text prompt, waits for completion, then saves every URL found in the task output to disk.
 Command text-to-image generates a concept image from a text prompt, waits for completion, then saves every URL found in the task output to disk.
text-to-model command
Command text-to-model generates a 3D model from a text prompt, waits for completion, then saves the resulting GLB to disk.
 Command text-to-model generates a 3D model from a text prompt, waits for completion, then saves the resulting GLB to disk.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.