Go API 参考

导入

import (
    "context"
    "errors"
    "fmt"
    "io"
    "os"
    joytoken "github.com/jd-opensource/joytoken-sdk-go"
)

NewClient

ctx := context.Background()
client := joytoken.NewClient(
	joytoken.WithAPIKey(os.Getenv("JOY_TOKEN_API_KEY")),
	joytoken.WithAPIBaseURL(os.Getenv("JOY_TOKEN_API_BASE_URL")),
)

Gateway 只有一个 Chat Completions 模型入口。Responses 使用原生 /openai/v1/responses；Messages 在 SDK 本地与 Chat Completions 相互转换，不会发送 Anthropic HTTP 请求或 anthropic-version 请求头。

模型调用、模型元数据和价格接口必须配置 WithAPIKey。缺少 Key 时，这些方法会在发送请求前返回 joytoken.ErrMissingAPIKey。ListModels 是唯一无需鉴权的目录方法。

方法选择

只有在请求级与 Client 注册工具都不存在时，基础方法才会自动运行 SDK 默认兜底工具。调用方工具必须使用显式 Run* 才会由 SDK 执行。

兼容接口方法

completion, err := client.CreateChatCompletion(ctx, joytoken.ChatCompletionRequest{
    Model: joytoken.ModelAuto,
    Messages: []joytoken.ChatMessage{
        {Role: "user", Content: "Hello"},
    },
    Tools: []joytoken.ChatTool{},
})

stream, err := client.StreamChatCompletion(ctx, joytoken.ChatCompletionRequest{
    Model: joytoken.ModelAuto,
    Messages: []joytoken.ChatMessage{
        {Role: "user", Content: "Hello"},
    },
    Tools: []joytoken.ChatTool{},
})
if err != nil {
    return err
}
defer stream.Close()
chunk, err := stream.Recv()

response, err := client.CreateResponse(ctx, joytoken.ResponseRequest{
    Model: joytoken.ModelAuto,
    Input: "用一句话解释 JoyToken。",
    Tools: []joytoken.ResponseTool{},
})
if err != nil {
    return err
}
fmt.Println(response.OutputText())

stream, err := client.StreamResponse(ctx, joytoken.ResponseRequest{
    Model: joytoken.ModelAuto,
    Input: "Say hello",
    Tools: []joytoken.ResponseTool{},
})
if err != nil {
    return err
}
defer stream.Close()
for {
    event, err := stream.Recv()
    if errors.Is(err, io.EOF) {
        break
    }
    if err != nil {
        return err
    }
    fmt.Print(event.Delta)
}

image, err := client.GenerateImage(ctx, joytoken.ImageGenerationRequest{
    Model:          joytoken.ModelAuto,
    Prompt:         "A neon JoyToken logo on a black background",
    Size:           "1024x1024",
})
if err != nil {
    return err
}
if len(image.Data) == 0 {
	return fmt.Errorf("图片响应不包含数据")
}
fmt.Println(image.Data[0].URL)

edited, err := client.EditImage(ctx, joytoken.ImageEditRequest{
    Model:  joytoken.ModelAuto,
    Image:  "https://picsum.photos/512/512",
    Prompt: "Add a neon JoyToken logo in the top-right corner",
    Size:   "1024x1024",
})
if err != nil {
    return err
}
if len(edited.Data) == 0 {
    return fmt.Errorf("image response contained no data")
}
fmt.Println(edited.Data[0].URL)

工具调用

工具所有权遵循同一套优先级：

1. 非 nil 的请求 Tools（包含空切片）会原样复制，并关闭所有默认工具。
2. 否则 Client 注册工具会整体替换默认工具。
3. 只有前两者都不存在时，SDK 才注入并自动执行默认兜底工具。

Create* 与原始 Stream* 不会执行请求级或 Client 注册工具。显式 Run* 只执行同名 handler。基础 Create* 只会自动运行规则 3 中由 SDK 自有的默认工具。

注册工具

构造 Client 时使用 WithToolHandler（或 WithTools）注册工具。非空注册集会整体替换默认本地工具，不做合并。

client := joytoken.NewClient(
    joytoken.WithAPIKey(os.Getenv("JOY_TOKEN_API_KEY")),
    joytoken.WithAPIBaseURL(os.Getenv("JOY_TOKEN_API_BASE_URL")),
    joytoken.WithToolHandler(
        "get_weather",
        "Get the current weather for a city.",
        map[string]any{
            "type": "object",
            "properties": map[string]any{
                "city": map[string]any{"type": "string"},
            },
            "required": []string{"city"},
        },
        func(ctx context.Context, input any, _ joytoken.ToolExecutionContext) (any, error) {
            args, _ := input.(map[string]any)
            return map[string]any{"city": args["city"], "tempC": 22}, nil
        },
    ),
)

RunChatCompletion

result, err := client.RunChatCompletion(ctx, joytoken.ChatCompletionRequest{
    Model: joytoken.ModelAuto,
    Messages: []joytoken.ChatMessage{
        {Role: "user", Content: "What is 2+2?"},
    },
}, joytoken.RunChatOptions{MaxSteps: 8})
if err != nil {
    return err
}
fmt.Println(result.FinalText, result.StoppedBy, result.FinishReason)

运行有轮数上限的 Chat Completions 工具循环。RunChatOptions.MaxSteps 限制轮数(为 0 时使用默认值 8)。返回 *RunChatResult,包含 FinalText、Messages、逐轮 Steps、StoppedBy 以及与 Provider 无关的 FinishReason。

RunResponse / RunMessage / 流式 Run

RunResponse 在 Responses 原生 items 上运行循环，RunMessage 在 Messages 兼容内容块上运行循环。RunChatCompletionStream、RunResponseStream 与 RunMessageStream 都支持文本增量和工具结果回调，并返回最终聚合响应。

ToolCall.ExtraContent 保存不透明的厂商扩展字段，序列化为 extra_content。SDK 会在非流式与流式续跑、Messages tool_use 转换、Responses function-call items 以及 Agent 循环中原样保留它。Gemini 的 google.thought_signature 即为一例。手写循环必须保留完整的返回工具调用，而非仅重建其标准字段。另有一个位于顶层的 thought_signature，对于像 Gemini 这类直接把它返回在 tool_call 顶层的厂商，SDK 将其暴露为 ToolCall.ThoughtSignature（序列化为 thought_signature），并在续跑轮次原样（verbatim）保留与回传。

后续轮次失败时，显式 Run* 方法会同时返回错误和非 nil 的部分结果。已完成的 Steps、工具结果以及累积的 Messages 或 Input 都可用于诊断与恢复。

请求级声明不含可执行 Go 代码。Run* 请求传入 Tools 时，只有 Client 上注册的同名 handler 可以执行。未知名称会产生结构化 tool_handler_not_found 结果并回传模型。

Responses 托管工具

WithDefaultBuiltinTools(true) 当前只启用 web_search_preview，默认关闭。托管 file_search 必须显式提供有效 vector_store_ids。不要同时发送 web_search、web_search_20250305、web_search_preview 等厂商别名；未知类型可能被 Gateway 拒绝。

应通过 Responses 结果中是否存在 web_search_call output item，确认托管搜索确实执行。

有副作用的工具受门控保护

默认本地工具集包含可自由运行的只读工具(file_read、list_dir、file_search),以及两个始终会声明给模型、但在执行时默认安全拒绝的副作用工具:file_write 和 shell。它们仅在你提供审批回调时才会运行。

client := joytoken.NewClient(
    joytoken.WithAPIKey(os.Getenv("JOY_TOKEN_API_KEY")),
    // 逐条批准或拒绝 shell 命令;未提供回调即拒绝所有调用。
    joytoken.WithShellPermission(func(ctx context.Context, req joytoken.ShellPermissionRequest) (bool, error) {
        return req.Command == "ls" && req.WorkingDir == "/tmp", nil
    }),
    joytoken.WithFilePermission(func(ctx context.Context, req joytoken.FilePermissionRequest) (bool, error) {
        return false, nil // 拒绝所有写入
    }),
)

ShellPermissionRequest 包含 Command 和 WorkingDir；FilePermissionRequest 包含解析后的 Root。使用 WithShellWorkspace 和 WithFileWorkspace 配置根目录，便于宿主准确展示和限制执行位置。若想彻底移除某个工具而非只是门控，可按名称排除：

// 从默认集中移除 shell 和 file_write;只读工具保留。
joytoken.WithoutDefaultTools("shell", "file_write")

WithoutDefaultTools 只过滤默认工具——你通过 WithTools / WithToolHandler 注册的工具始终优先,永不会被移除。

循环的每个续轮都会保留已解析的工具声明，并且每个工具结果只追加一次。首个工具调用后，强制工具选择会放宽为 auto，让模型能够返回最终回答。默认循环上限为 8 轮。

ListModels

models, err := client.ListModelsWithOptions(ctx, joytoken.ListModelsOptions{
	Locale: joytoken.ModelLocaleZH,
})

调用无需鉴权的 GET /api/v1/models 接口。ModelLocaleZH 返回中文描述，ModelLocaleEN 返回英文描述。ListModels(ctx) 不传 locale，使用接口默认的英文描述。SDK 保留 HTTP 响应层级，目录项位于 models.Data.Models。

GetModelMeta

metadata, err := client.GetModelMeta(ctx)

携带已配置的 API Key 调用 GET /api/v1/models/meta，返回目录筛选元数据。

GetPricing

pricing, err := client.GetPricing(ctx)

携带已配置的 API Key 调用 GET /api/v1/pricing，返回面向客户的档位兑换价格元数据。

ErrMissingAPIKey

if errors.Is(err, joytoken.ErrMissingAPIKey) {
    // 重试前配置 WithAPIKey 或 JOY_TOKEN_API_KEY。
}

超时与重试策略

WithTimeout 覆盖完整非流式请求，或流被消费期间的完整生命周期。传非正值可禁用 SDK 超时。

WithMaxRetries(n) 使用带上限的指数退避、抖动和 Retry-After 支持，对 HTTP 429、5xx 与传输错误进行重试。默认值为 0。只有在可以接受重放非幂等模型 POST，以及潜在重复执行或计费时才应开启。

APIError

var apiErr *joytoken.APIError
if errors.As(err, &apiErr) {
	fmt.Println(apiErr.StatusCode, apiErr.RequestID, apiErr.Body)
}

ChatCompletionResponse.Metadata、Chat 流 metadata 与 Messages 适配层 metadata 会保留 Gateway 返回的路由和计费信息。排查时可记录 request ID 与停止原因，但不要记录 API Key 或未脱敏的敏感工具输入。