Go SDK 使用指南

纯 stdlib 零依赖，内置指数退避重试、PollUntilDone 轮询助手、SDKError 统一错误。

安装与初始化

go get modelsyncbridge/sdk

client := modelsyncbridge.NewClient(modelsyncbridge.Config{
    BaseURL: "http://localhost:8080",
    APIKey:  "your-access-key",   // 可选；服务端开启鉴权后必填
})

方法速查

方法	说明
`Health(ctx)`	服务健康
`Generate(ctx, req)`	提交文/图→3D 任务
`BatchGenerate(ctx, req)`	批量提交（≤100）
`Query(ctx, taskID)`	查任务状态/进度/结果
`Cancel(ctx, taskID)`	取消任务
`ListProviders(ctx)`	厂商列表（含支持模型）
`DownloadModel(ctx, taskID, fileType)`	下载 GLB / PNG
`StatsSummary(ctx)` / `StatsProviders(ctx)` / `ProviderScores(ctx)`	统计 / 评分 / 熔断
`PollUntilDone(ctx, taskID, cfg)`	阻塞轮询直到终态

所有方法末尾可选 CallOption：WithRetry(...)、WithTimeout(...)。

核心示例

// 文生 3D（Hyper3D）：提交 → 轮询 → 下载
gen, _ := client.Generate(ctx, &modelsyncbridge.GenerateRequest{
    Prompt: "cyberpunk sword, neon glow",
    Model:  "hyper3d-rodin-1.5",  // 可选：指定模型，中台自动路由到 Hyper3D 并从其 key 池选一个 key
})
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)
}

// 图生 3D（Hyper3D）：填 ReferenceImage 即图生模式，model 指定图生模型
client.Generate(ctx, &modelsyncbridge.GenerateRequest{
    ReferenceImage: "https://example.com/ref.png",
    Prompt:         "keep the same shape",       // 可选风格提示
    Model:          "hyper3d-rodin-1.5-image",
})

// 批量（≤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

// 指定厂商 + 模型（不走智能调度）
client.Generate(ctx, &modelsyncbridge.GenerateRequest{
    Prompt: "test", Provider: "hyper3d", Model: "hyper3d-rodin-1.5",
})

// 上游生成参数（如 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",
    },
}) // 按各厂商 API 的原始格式透传（详见 README）

重试与轮询配置

配置	字段	默认
`RetryConfig`	`MaxRetries` / `InitialBackoff` / `MaxBackoff`	`3` / `500ms` / `10s`
`PollConfig`	`InitialInterval` / `MaxInterval` / `Timeout`	`3s` / `30s` / `10min`

重试规则：429 / 5xx 及错误码 RATE_LIMITED / PROVIDER_ERROR / NO_AVAILABLE_PROVIDER 自动重试；401 / 403 / 404 / 参数错误立即失败。

错误处理

错误统一为 *SDKError（Code / Message / Status / Err，IsRetryable()），用 AsSDKError 断言。常用常量：

常量	值	场景
`ErrInvalidParam`	`INVALID_PARAM`	参数错误
`ErrProviderNotFound`	`PROVIDER_NOT_FOUND`	厂商不存在
`ErrNoAvailable`	`NO_AVAILABLE_PROVIDER`	无可用厂商
`ErrTaskNotFound`	`TASK_NOT_FOUND`	任务不存在
`ErrRateLimited`	`RATE_LIMITED`	限流
`ErrAuthFailed`	`AUTH_FAILED`	Key 错误

完整 12 个常量见 sdk/types.go。网络层错误 Code="NETWORK"，默认可重试。

运行完整示例

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

FilesExpand file tree

sdk.zh.md

Latest commit

History