> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs-staging.joytokens.ai/llms.txt.

# 示例

> 完整、可复制运行的客户端 SDK 示例

本页每个示例都是**自包含**的：包含 import、环境读取和错误处理，复制单个代码块即可运行。请先设置：

```bash
export JOY_TOKEN_API_KEY="sk-xxx"
export JOY_TOKEN_OPENAI_BASE_URL="https://api-staging.joytokens.ai/openai/v1"
export JOY_TOKEN_ANTHROPIC_BASE_URL="https://api-staging.joytokens.ai/anthropic/v1"
```

所有请求都使用 `model: "auto"`，没有模型环境变量。Base URL 来自 [环境](/zh/user-guide/environments)。

## Chat Completions

#### TypeScript

```ts
import { JoyTokenClient } from "@joytoken/client-sdk-ts";

const apiKey = process.env.JOY_TOKEN_API_KEY;
if (!apiKey) throw new Error("JOY_TOKEN_API_KEY is required");

const joytoken = new JoyTokenClient({
  apiKey,
  openAIBaseUrl: process.env.JOY_TOKEN_OPENAI_BASE_URL,
});

const completion = await joytoken.chat.completions.create({
  model: "auto",
  messages: [{ role: "user", content: "Say hello in one sentence." }],
});

console.log(completion.choices[0]?.message?.content);
```

#### Go

```go
package main

import (
    "context"
    "fmt"
    "os"

    joytoken "github.com/jd-opensource/joytoken-sdk-go"
)

func main() {
    ctx := context.Background()
    client := joytoken.NewClient(
        joytoken.WithAPIKey(os.Getenv("JOY_TOKEN_API_KEY")),
        joytoken.WithOpenAIBaseURL(os.Getenv("JOY_TOKEN_OPENAI_BASE_URL")),
    )

    completion, err := client.CreateChatCompletion(ctx, joytoken.ChatCompletionRequest{
        Model:    joytoken.ModelAuto,
        Messages: []joytoken.ChatMessage{{Role: "user", Content: "Say hello in one sentence."}},
    })
    if err != nil {
        panic(err)
    }
    fmt.Println(completion.Choices[0].Message.Content)
}
```

## Responses

#### TypeScript

```ts
import { JoyTokenClient } from "@joytoken/client-sdk-ts";

const apiKey = process.env.JOY_TOKEN_API_KEY;
if (!apiKey) throw new Error("JOY_TOKEN_API_KEY is required");

const joytoken = new JoyTokenClient({
  apiKey,
  openAIBaseUrl: process.env.JOY_TOKEN_OPENAI_BASE_URL,
});

const response = await joytoken.responses.create({
  model: "auto",
  input: "Say hello in one sentence.",
});

console.log(response.output?.[0]?.content?.[0]?.text);
```

#### Go

```go
client := joytoken.NewClient(
    joytoken.WithAPIKey(os.Getenv("JOY_TOKEN_API_KEY")),
    joytoken.WithOpenAIBaseURL(os.Getenv("JOY_TOKEN_OPENAI_BASE_URL")),
)

response, err := client.CreateResponse(ctx, joytoken.ResponseRequest{
    Model: joytoken.ModelAuto,
    Input: "Say hello in one sentence.",
})
if err != nil {
    return err
}
fmt.Println(response.OutputText())
```

## Anthropic Messages

#### TypeScript

```ts
import { JoyTokenClient } from "@joytoken/client-sdk-ts";

const apiKey = process.env.JOY_TOKEN_API_KEY;
if (!apiKey) throw new Error("JOY_TOKEN_API_KEY is required");

const joytoken = new JoyTokenClient({
  apiKey,
  anthropicBaseUrl: process.env.JOY_TOKEN_ANTHROPIC_BASE_URL,
});

const message = await joytoken.messages.create({
  model: "auto",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Say hello in one sentence." }],
});

console.log(message.content[0]?.text);
```

#### Go

```go
client := joytoken.NewClient(
    joytoken.WithAPIKey(os.Getenv("JOY_TOKEN_API_KEY")),
    joytoken.WithAnthropicBaseURL(os.Getenv("JOY_TOKEN_ANTHROPIC_BASE_URL")),
)

message, err := client.CreateMessage(ctx, joytoken.MessageRequest{
    Model:     "auto",
    MaxTokens: 1024,
    Messages:  []joytoken.MessageParam{{Role: "user", Content: "Say hello in one sentence."}},
})
if err != nil {
    return err
}
fmt.Println(message.Content[0].Text)
```

## Streaming 流式输出

流式适用于 Chat Completions、Responses 和 Anthropic Messages。下例演示 Chat Completions 的流式输出。

#### TypeScript

```ts
for await (const chunk of joytoken.chat.completions.stream({
  model: "auto",
  messages: [{ role: "user", content: "Count from 1 to 5." }],
})) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
```

#### Go

```go
stream, err := client.StreamChatCompletion(ctx, joytoken.ChatCompletionRequest{
    Model:    joytoken.ModelAuto,
    Messages: []joytoken.ChatMessage{{Role: "user", Content: "Count from 1 to 5."}},
})
if err != nil {
    return err
}
defer stream.Close()

for {
    chunk, err := stream.Recv()
    if errors.Is(err, io.EOF) {
        break
    }
    if err != nil {
        return err
    }
    fmt.Print(chunk.Choices[0].Delta["content"])
}
```

## Orchestration

`model: "auto"` 请求可能被路由到\*\*编排（多任务规划）\*\*模式。网关会把请求拆分为子任务、分别执行，再聚合结果。SDK 返回的是网关原始结构，因此需要按其形态分支处理：

* `choices[0].message.content` 是**一段 JSON 编码的数组**（每个元素为 `{ "title", "content" }` 的每任务输出），而非普通字符串——渲染前需先解析。顶层的 `plan` 字段可用于确认是否为编排模式。
* `metadata` 是一个**数组**，每个任务对应一条,包括保留项 `__planner__`（`task_seq: 0`）与 `__final__`（`task_seq: 4`）。将各条的 `billing.credits_used` 相加即为总费用。
* 流式场景下，先到达一个 planning 事件（一个 `orchestration.phase` 为 `planning` 的 chunk，携带有序的 `plan`），其后紧跟 `__planner__` 的 metadata 事件；随后每个任务的完整正文作为一个 chunk 到达，该 chunk 携带 `orchestration` 字段（`task_id`、`task_seq`、`task_status`、`title`），每个任务之后再跟一个独立的 metadata 事件（值为单个对象，而非数组），最后才是 `[DONE]`。

完整字段参考见 [路由](/zh/user-guide/routing#orchestration-multi-task-planning)。

#### TypeScript

```ts
type TaskOutput = { title: string; content: string };

const completion = await joytoken.chat.completions.create({
  model: "auto",
  messages: [{ role: "user", content: "帮我规划深圳一日游。" }],
});

const raw = completion.choices[0]?.message?.content ?? "[]";
const metadata = (completion as any).metadata ?? [];

// 编排模式：content 是一个任务输出的 JSON 数组。
if ((completion as any).plan && Array.isArray((completion as any).plan)) {
  const tasks: TaskOutput[] = JSON.parse(raw);
  for (const task of tasks) {
    console.log(`## ${task.title}\n${task.content}\n`);
  }

  const totalCredits = metadata.reduce(
    (sum: number, m: any) => sum + (m.billing?.credits_used ?? 0),
    0,
  );
  console.log(`总积分消耗: ${totalCredits}`);
} else {
  console.log(raw); // 普通单模型响应
}
```

#### Go

```go
type TaskOutput struct {
    Title   string `json:"title"`
    Content string `json:"content"`
}

resp, err := client.CreateChatCompletion(ctx, joytoken.ChatCompletionRequest{
    Model:    joytoken.ModelAuto,
    Messages: []joytoken.ChatMessage{{Role: "user", Content: "帮我规划深圳一日游。"}},
})
if err != nil {
    return err
}

// 编排模式：Plan 非空且 Content 为 JSON 数组。
if len(resp.Plan) > 0 {
    var tasks []TaskOutput
    if err := json.Unmarshal([]byte(resp.Choices[0].Message.Content), &tasks); err != nil {
        return err
    }
    for _, task := range tasks {
        fmt.Printf("## %s\n%s\n\n", task.Title, task.Content)
    }

    var totalCredits float64
    for _, m := range resp.Metadata {
        totalCredits += m.Billing.CreditsUsed
    }
    fmt.Printf("总积分消耗: %v\n", totalCredits)
} else {
    fmt.Println(resp.Choices[0].Message.Content) // 普通单模型响应
}
```

## Model list 模型列表

#### TypeScript

```ts
const models = await joytoken.models.list({ locale: "zh" });

for (const model of models.data.models) {
  console.log(model.modelId);
}
```

传入 `{ locale: "zh" }` 获取中文描述；省略 `locale` 默认英文。目录项在 `models.data.models`。

#### Go

```go
models, err := client.ListModelsWithOptions(ctx, joytoken.ListModelsOptions{
    Locale: joytoken.ModelLocaleZH,
})
if err != nil {
    return err
}
for _, model := range models.Data.Models {
    fmt.Println(model.ModelID)
}
```

使用 `joytoken.ModelLocaleZH` 获取中文描述。`ListModels(ctx)` 不设置 `locale`（API 默认英文）。目录项在 `models.Data.Models`。

## Error handling 错误处理

#### TypeScript

```ts
import { JoyTokenAPIError, JoyTokenClient } from "@joytoken/client-sdk-ts";

const apiKey = process.env.JOY_TOKEN_API_KEY;
if (!apiKey) throw new Error("JOY_TOKEN_API_KEY is required");

const joytoken = new JoyTokenClient({ apiKey });

try {
  await joytoken.chat.completions.create({
    model: "auto",
    messages: [{ role: "user", content: "你好" }],
  });
} catch (error) {
  if (error instanceof JoyTokenAPIError) {
    console.error(error.status, error.requestId, error.body);
  }
  throw error;
}
```

#### Go

```go
_, err := client.ListModels(ctx)
if err != nil {
    var apiErr *joytoken.APIError
    if errors.As(err, &apiErr) {
        fmt.Println(apiErr.StatusCode, apiErr.RequestID, apiErr.Body)
    }
    return err
}
```

## Run the example project 运行示例项目

#### TypeScript

```bash
git clone https://github.com/jd-opensource/joytoken-sdk-ts.git
cd joytoken-sdk-ts
pnpm install

export JOY_TOKEN_API_KEY="sk-xxx"

cd example
pnpm live
```

#### Go

```bash
git clone https://github.com/jd-opensource/joytoken-sdk-go.git
cd joytoken-sdk-go/example
export JOY_TOKEN_API_KEY="sk-xxx"
go run ./live
```

live 示例和 Client SDK 请求始终使用 `model: "auto"`，没有模型环境变量。