> 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.

# 快速开始

> 3 步用客户端 SDK 发出第一条 JoyToken 请求

跑通一条端到端的请求。完整的可运行片段目录（流式、Anthropic、模型列表、错误处理）见 [示例](/zh/client-sdk/examples)。

## 前置条件

| 项目           | 值                                                               |
| ------------ | --------------------------------------------------------------- |
| API Key      | `JOY_TOKEN_API_KEY`                                             |
| API Base URL | 从 [环境](/zh/user-guide/environments) 选择 `JOY_TOKEN_API_BASE_URL` |
| 模型           | `auto`（不可配置）                                                    |
| TypeScript   | Node.js `18+`                                                   |
| Go           | Go `1.22+`                                                      |

## 第 1 步：设置环境

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

两个 SDK 默认使用 60 秒的请求/流式超时。仅当工作负载需要不同上限时再覆盖——TypeScript 用 `timeoutMs`，Go 用 `WithTimeout`。

## 第 2 步：安装

#### TypeScript

TypeScript 从 GitHub 分发，不在 npm registry 上。把包子目录加入 `package.json`：

```json
{
  "type": "module",
  "dependencies": {
    "@joytoken/client-sdk-ts": "git+https://github.com/jd-opensource/joytoken-sdk-ts.git#path:/client-sdk-ts"
  }
}
```

```bash
pnpm install
```

为保证可复现构建，请固定到某个发布 tag 或 commit，而不是跟随默认分支。

#### Go

```bash
go get github.com/jd-opensource/joytoken-sdk-go
```

为保证可复现的生产构建，请固定到某个发布 tag。

## 第 3 步：发出第一条请求

#### 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: "Reply with exactly: pong" }],
});

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: "Reply with exactly: pong"}},
    })
    if err != nil {
        panic(err)
    }
    fmt.Println(completion.Choices[0].Message.Content)
}
```

## 校验结果

| 位置          | 期望结果                            |
| ----------- | ------------------------------- |
| 程序输出        | `pong`                          |
| JoyToken 日志 | 请求到达 OpenAI Chat Completions 端点 |
| JoyToken 用量 | 记录到 token 与额度                   |

## 常见错误

| 错误                       | 处理                             |
| ------------------------ | ------------------------------ |
| `401 Unauthorized`       | 检查 `JOY_TOKEN_API_KEY` 是否存在且完整 |
| `403 Forbidden`          | 检查 API Key 策略是否允许 `auto` 或目标模型 |
| `402 insufficient_quota` | 检查钱包余额与 Key 预算                 |
| 超时                       | 增大 SDK 超时或检查到所选环境的连通性          |

## 下一步

* [示例](/zh/client-sdk/examples) —— 流式、Anthropic、模型列表、错误处理
* [TypeScript SDK](/zh/client-sdk/type-script-sdk/overview) · [Go SDK](/zh/client-sdk/go-sdk/overview) —— 客户端选项与工具调用