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

# 创建 API 密钥与使用

> 创建和管理 API 密钥

防护策略创建完成后，点击【API密钥】菜单，本页面用于创建和管理 API 密钥。

## 新建密钥

![创建 API 密钥](/_fern-files/_img/3531ab9d434b97e173b8c0f2de7c222d9f8fb1db530ed9101e35419a90febb29.webp)

点击右上角"创建新密钥"可打开创建弹窗，按需填写：

![创建 API 密钥弹窗](/_fern-files/_img/cfc0a0908d6a1abb1e3ae0b129f7c61525dd309ff4041f55c6d5908d01a14342.webp)

* **密钥名称**
* **过期时间**：如永不过期、30 天、90 天，或自定义时间
* **防护策略**：在《防护策略》菜单中已新建好的策略会同步拉取到下拉框内

> **Note**
>
> 每个用户最多只能同时存在 3 个可用密钥。

## 密钥列表

支持按参数筛选、按状态过滤。每行「⋮」可管理该密钥。

展示字段：**密钥名称、策略、等级、使用限额、过期时间、操作**。

其中**操作**点击后下拉框展示"详情"和"撤销"：

* **详情**：可查看密钥的身份信息、ID、创建时间、密钥前缀、策略配置等信息。
* **撤销**：可失效当前密钥，撤销后的密钥无法请求调用接口。

![API 密钥](/_fern-files/_img/4f13ef718ccc591b9f375335e09b12a72adaaf92b4f96a388bfa1fcdaa842a51.webp)![创建 API 密钥](/_fern-files/_img/e067544982503aa45176559184535e53424e5fc11dd682ece80a7727c3d6d81e.webp)

## API试炼场在线测试

API试炼场是内置的在线测试工具，无需编写代码即可直接与模型对话，适合快速验证密钥是否可用以及使用日志形式。

**左侧配置**

* **API Key**：显示已验证密钥，可重新验证。
* **策略**：展示所选密钥的策略名称、档位、商品、行业包、IP 白名单、日/周限额、模型黑名单。
* **生成参数**：温度、最大输出令牌数、流式响应开关。

**中间对话区**：输入问题即可与模型交互；底部可上传媒体、切换配置/检查器、发送。

**右侧面板**（可切换「概览 / 路由」）

* **概览**：请求摘要（状态、请求 ID、API Key、策略、档位、模型）、成本与 Token、延迟明细（总耗时、路由、首 Token、流式输出）。
* **路由**：用户设置、档位推荐（任务评分明细）、模型推荐（已选模型、命中概率、标签）及其他候选模型。

![API试炼场概览](/_fern-files/_img/0f7b6e07e490b0f0e9cc77ef382d29d85839db063439a5fe4bb94b72a0e49802.webp)![API试炼场路由](/_fern-files/_img/edcd2239d476f46f1d72af64a4b7ee28c45890fdbccbbb2dd1d58d298ac1ebd8.webp)

### API试炼场功能操作

**API key 验证**：API试炼场使用前需验证输入的 key 是否有效。其中 key 被首次创建成功来自 API 管理跳转时无需填写，系统自动验证。输入 key 后点击"验证 API key"，输入框上方显示验证结果。

![验证 API key](/_fern-files/_img/d280310aad82b767aac56f1190031e08610ce8a25ef130ddd6916666036c5a36.webp)

**生成参数 - 温度**：控制随机性。数值越低越稳定，越高越发散。默认 0.7，仅针对 API试炼场。

![生成参数 - 温度](/_fern-files/_img/b9b8de5ff3b312d6ae5dfbb7e4d085286e38c418e5496c14a885be53f3af98f9.webp)

**最大输出令牌数**：限制本次请求中模型回复的最大长度。超过时模型无法输出结果。当前默认 4096，仅针对 API试炼场。

**流式响应**：开启后会边生成边返回内容，更适合长回复和实时预览；关闭后等待完整响应一次性返回。当前默认开启，仅针对 API试炼场。

### 任务编排模式

功能定位：在 API试炼场中，当遇到较为复杂的对话任务，系统自动拆解为多步骤的执行计划并逐步完成（例如“生成一张沙滩→加海鸥→加旅人→加夕阳→按想法优化”的连续图像生成流程）。

![任务编排模式执行计划](/_fern-files/_img/e2f63a9f30d2d9f08630bdeb2e3d9ae1aaa1546eba6005bee76437a17f5033da.webp)![任务编排模式任务与概览](/_fern-files/_img/9a90e746b661508ed045496fba3a1d2af04bf9bc63c536c4f368301eaad5af20.webp)

**页面布局**：

**中间主区**：顶部展示用户输入的原始需求；下方是系统生成的结构化「执行计划」，按序号分节（如 1. 创建基础背景、2. 添加海鸥元素、3. 添加旅人元素、4. 添加夕阳、5. 整体艺术化优化、6. 最终效果方向），每节列出具体执行要点。

**底部输入框**：占位提示“你想知道什么？”，支持继续追问；左下角有「上传媒体」，右下角有「配置」「检查器」及发送按钮。

**右侧面板**：顶部切换「概览 / 任务」两个标签页。

**右侧「任务」标签页**：以卡片列出编排出的各子任务（01 规划、02 生成沙滩背景、03 添加海鸥旅人、04 创意优化与艺术化、05 汇总），每张卡片显示状态（已完成）、所用模型、备选模型、档位（经济档/旗舰档）、Credit 消耗，以及输入/输出 Token、缓存读写、首 Token 耗时、模型流式输出等执行明细。

**右侧「概览」标签页**：汇总整次请求信息——状态、请求 ID、API Key、策略、任务数；以及按档位统计的 Credit 消耗（旗舰档/标准档/经济档）、总 Credit 与折算 USD、总 Token 数、输入/输出 Token、缓存读写；「延迟」区展示总耗时与首 Token 耗时。

## 使用 API 调用示例

### 配置客户端

将复制的地址填入你的客户端或代码中作为 `base_url`，配合密钥即可开始调用。

### 代码示例

TypeScript（OpenAI SDK）：

```typescript
import { JoyTokenClient } from "@joytoken/client-sdk-ts";

const joytoken = new JoyTokenClient({
  apiKey,
  openAIBaseUrl: process.env.JOY_TOKEN_OPENAI_BASE_URL,
  timeoutMs: 60_000,
});
```

**非流式：**

```typescript
const completion= await joytoken.chat.completions.create({
  model: "auto",
  messages: [{ role: "user", content: "Reply with exactly: pong" }],
});
console.log(completion.choices[0]?.message?.content);
```

**流式：**

```typescript
for await (const chunk of joytoken.chat.completions.stream({
  model: "auto",
  messages: [{ role: "user", content: "Write one short paragraph." }],
})) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
```

**Claude 原始格式：**

```bash
curl -sS -X POST "$JOY_TOKEN_ANTHROPIC_BASE_URL/messages" \
  -H "x-api-key: $JOY_TOKEN_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [
      { "role": "user", "content": "只回复：pong" }
    ],
    "temperature": 0.7,
    "max_tokens": 1024,
    "stream": false
  }'
```

### 支持的接口端点

<table>
  <thead>
    <tr>
      <th>
        接口
      </th>

      <th>
        方法与路径
      </th>

      <th>
        说明
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        Chat Completions
      </td>

      <td>
        `POST /openai/v1/chat/completions`
      </td>

      <td>
        对话生成，支持流式输出
      </td>
    </tr>

    <tr>
      <td>
        Responses
      </td>

      <td>
        `POST /openai/v1/responses`
      </td>

      <td>
        OpenAI Responses 格式生成
      </td>
    </tr>

    <tr>
      <td>
        Image Generations
      </td>

      <td>
        `POST /openai/v1/images/generations`
      </td>

      <td>
        文生图
      </td>
    </tr>

    <tr>
      <td>
        Anthropic Messages
      </td>

      <td>
        `POST /anthropic/v1/messages`
      </td>

      <td>
        Anthropic Messages 格式生成
      </td>
    </tr>

    <tr>
      <td>
        List Models
      </td>

      <td>
        `GET /api/v1/models`
      </td>

      <td>
        查询模型目录
      </td>
    </tr>

    <tr>
      <td>
        Model Filter Metadata
      </td>

      <td>
        `GET /api/v1/models/meta`
      </td>

      <td>
        查询模型过滤选项
      </td>
    </tr>

    <tr>
      <td>
        Pricing
      </td>

      <td>
        `GET /api/v1/pricing`
      </td>

      <td>
        查询 tier 兑换汇率
      </td>
    </tr>
  </tbody>
</table>