Go SDK Guide

Pure stdlib, zero dependencies. Built-in exponential-backoff retries, a PollUntilDone polling helper, and unified SDKError.

Install & init

go get modelsyncbridge/sdk

client := modelsyncbridge.NewClient(modelsyncbridge.Config{
    BaseURL: "http://localhost:8080",
    APIKey:  "your-access-key",   // optional; required once server auth is on
})

Methods

Method	Description
`Health(ctx)`	Service health
`Generate(ctx, req)`	Submit text/image→3D task
`BatchGenerate(ctx, req)`	Batch submit (≤100)
`Query(ctx, taskID)`	Task status / progress / result
`Cancel(ctx, taskID)`	Cancel task
`ListProviders(ctx)`	Providers (incl. supported models)
`DownloadModel(ctx, taskID, fileType)`	Download GLB / PNG
`StatsSummary(ctx)` / `StatsProviders(ctx)` / `ProviderScores(ctx)`	Stats / scores / breakers
`PollUntilDone(ctx, taskID, cfg)`	Block until a terminal state

Every method accepts an optional trailing CallOption: WithRetry(...), WithTimeout(...).

Core examples

// Text-to-3D (Hyper3D): submit → poll → download
gen, _ := client.Generate(ctx, &modelsyncbridge.GenerateRequest{
    Prompt: "cyberpunk sword, neon glow",
    Model:  "hyper3d-rodin-1.5",  // optional: pick a model; the bridge routes to Hyper3D & picks one of its keys
})
result, _ := client.PollUntilDone(ctx, gen.TaskID, modelsyncbridge.PollConfig{
    InitialInterval: 3 * time.Second,
    Timeout:         10 * time.Minute,
})
if result.Status == modelsyncbridge.StatusSuccess {
    data, _, _ := client.DownloadModel(ctx, gen.TaskID, "model")
    _ = os.WriteFile("model.glb", data, 0o644)
}

// Image-to-3D (Hyper3D): ReferenceImage triggers image mode, model selects the image model
client.Generate(ctx, &modelsyncbridge.GenerateRequest{
    ReferenceImage: "https://example.com/ref.png",
    Prompt:         "keep the same shape",       // optional style hint
    Model:          "hyper3d-rodin-1.5-image",
})

// Batch (≤100)
resp, _ := client.BatchGenerate(ctx, &modelsyncbridge.BatchGenerateRequest{
    Requests: []modelsyncbridge.GenerateRequest{
        {Prompt: "a red sports car"},
        {Prompt: "a castle on a mountain"},
    },
}) // resp.TaskIDs / resp.Summary

// Force provider + model (bypasses smart dispatch)
client.Generate(ctx, &modelsyncbridge.GenerateRequest{
    Prompt: "test", Provider: "hyper3d", Model: "hyper3d-rodin-1.5",
})

// Upstream generation options (e.g. Tripo3D): texture/pbr/quad/texture_quality/geometry_quality...
client.Generate(ctx, &modelsyncbridge.GenerateRequest{
    Prompt: "an ancient temple, low-poly",
    Model:  "v3.1-20260211",
    Options: map[string]interface{}{
        "texture":          true,
        "pbr":              true,
        "quad":             false,
        "texture_quality":  "extreme",
        "geometry_quality": "detailed",
    },
}) // forwarded in the format each provider's API expects (see README)

Retry & poll config

Config	Fields	Defaults
`RetryConfig`	`MaxRetries` / `InitialBackoff` / `MaxBackoff`	`3` / `500ms` / `10s`
`PollConfig`	`InitialInterval` / `MaxInterval` / `Timeout`	`3s` / `30s` / `10min`

Retry rule: 429 / 5xx and codes RATE_LIMITED / PROVIDER_ERROR / NO_AVAILABLE_PROVIDER auto-retry; 401 / 403 / 404 / bad params fail immediately.

Errors

Errors are *SDKError (Code / Message / Status / Err, IsRetryable()), asserted with AsSDKError. Common constants:

Constant	Value	When
`ErrInvalidParam`	`INVALID_PARAM`	Bad params
`ErrProviderNotFound`	`PROVIDER_NOT_FOUND`	Unknown provider
`ErrNoAvailable`	`NO_AVAILABLE_PROVIDER`	No provider available
`ErrTaskNotFound`	`TASK_NOT_FOUND`	Task missing
`ErrRateLimited`	`RATE_LIMITED`	Rate limited
`ErrAuthFailed`	`AUTH_FAILED`	Bad key

Full 12 constants live in sdk/types.go. Network errors use Code="NETWORK" and are retryable by default.

Run the full example

MSB_BASE_URL=http://localhost:8080 go run ./sdk/example_main.go

FilesExpand file tree

sdk.md

Latest commit

History