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

# API 指南

> JoyToken 当前公开 API 的接入方式

JoyToken 面向开发者提供 OpenAI 兼容和 Anthropic 兼容的模型接口。

## 通用 API

Base URL 使用 [环境](/zh/user-guide/environments) 中的 `JOY_TOKEN_API_BASE_URL`。

| 接口                        | 认证                   | 用途          |
| ------------------------- | -------------------- | ----------- |
| `GET /api/v1/models`      | 无                    | 公开模型列表      |
| `GET /api/v1/models/meta` | Bearer 或 `X-API-Key` | 目录筛选元数据     |
| `GET /api/v1/pricing`     | Bearer 或 `X-API-Key` | 面向客户的档位兑换价格 |

模型描述可通过可选的 `locale` 查询参数指定语言：`locale=zh` 返回中文，`locale=en` 返回英文；不传时默认返回英文。

```bash
curl -sS "https://api-staging.joytokens.ai/api/v1/models?locale=zh"
```

## 选择协议接口

#### OpenAI

| 项目       | 值                                            |
| -------- | -------------------------------------------- |
| 接口       | `POST /openai/v1/chat/completions`           |
| Base URL | `https://api-staging.joytokens.ai/openai/v1` |
| 认证       | `Authorization: Bearer $JOY_TOKEN_API_KEY`   |
| 响应内容     | `choices[0].message.content`                 |

Responses 接口为 `POST /openai/v1/responses`。`input` 支持字符串或 message input items；非流式文本位于 `output[0].content[0].text`。

```bash
curl -N -sS -X POST "https://api-staging.joytokens.ai/openai/v1/responses" \
  -H "Authorization: Bearer $JOY_TOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "input": "用一句话解释 JoyToken。",
    "instructions": "保持简洁。",
    "max_output_tokens": 256,
    "stream": false
  }'
```

图片生成接口为 `POST /openai/v1/images/generations`。`model` 必须为 `auto`，`prompt` 为必填字段。`n`、`size`、`quality`、`style`、`response_format` 等图片选项会透传给所选 Provider；请省略 Provider 特有选项，除非所有候选图片模型都支持该选项。

图片生成仅支持非流式响应。不要传 `stream: true`，也不要按 SSE 消费此接口：保持请求连接，直到 JoyToken 在生成完成后一次性返回完整的 `application/json`。生成图片位于 `data`；根据 `response_format` 从 `data[0].url` 或 `data[0].b64_json` 读取结果。

```bash
curl -sS -X POST "https://api-staging.joytokens.ai/openai/v1/images/generations" \
  -H "Authorization: Bearer $JOY_TOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: image-$(date +%s%3N)" \
  -d '{
    "model": "auto",
    "prompt": "A neon JoyToken logo on a black background",
    "n": 1,
    "size": "1024x1024"
  }'
```

```json
{
  "created": 1793395200,
  "data": [
    {
      "url": "https://example.com/generated.png",
      "revised_prompt": "A neon JoyToken logo on a black background"
    }
  ]
}
```

```bash
curl -N -sS -X POST "https://api-staging.joytokens.ai/openai/v1/chat/completions" \
  -H "Authorization: Bearer $JOY_TOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: test-$(date +%s%3N)" \
  -d '{
    "model": "auto",
    "messages": [
      { "role": "user", "content": "你好，帮我测试一下网关链路" }
    ],
    "temperature": 0.7,
    "max_tokens": 1024,
    "stream": false
  }'
```

#### Anthropic

| 项目       | 值                                               |
| -------- | ----------------------------------------------- |
| 接口       | `POST /anthropic/v1/messages`                   |
| Base URL | `https://api-staging.joytokens.ai/anthropic/v1` |
| 认证       | `x-api-key: $JOY_TOKEN_API_KEY`                 |
| 响应内容     | `content[0].text`                               |

```bash
curl -N -sS -X POST "https://api-staging.joytokens.ai/anthropic/v1/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": "你好，帮我测试一下网关链路" }
    ],
    "temperature": 0.7,
    "max_tokens": 1024,
    "stream": false
  }'
```

> **Warning**
>
> 不要在同一个请求里同时传 `Authorization` 和 `X-API-Key`。如果两个都存在，当前网关会优先读取 `X-API-Key`。

## 视频生成 / 视频编辑

视频接口为异步三段式任务模型，适用模型 `Doubao-Seedance-2.5`（`model` 省略时为 `auto`，由网关在视频模型池中自动路由）：

| 步骤     | 接口                                        | 说明                                  |
| ------ | ----------------------------------------- | ----------------------------------- |
| 创建生成任务 | `POST /openai/v1/videos`                  | 文生视频 / 图生视频 / 首尾帧，返回 `task_id`（202） |
| 创建编辑任务 | `POST /openai/v1/videos/edits`            | 多视频拼接，响应与生成任务一致                     |
| 轮询状态   | `GET /openai/v1/videos/{task_id}`         | 200，编辑任务与生成任务共用                     |
| 下载成片   | `GET /openai/v1/videos/{task_id}/content` | 302 跳转到成片 URL                       |

生成入口支持三种方式：文生视频（仅 `prompt`，必填）、图生视频（`input_reference` 单图或多图，`prompt` 可省略）、首尾帧生视频（`first_frame` / `last_frame`，`prompt` 可省略）。生成入口不接受 `input_video`；多视频拼接请走编辑入口，编辑入口必须至少携带一种媒体输入（`input_reference` / `first_frame` / `last_frame` / `input_video`）。

```bash
curl -sS -X POST "https://api-staging.joytokens.ai/openai/v1/videos" \
  -H "Authorization: Bearer $JOY_TOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "prompt": "一只橘猫在雨中的东京街头奔跑，电影感运镜",
    "duration": 8,
    "size": "1280x720"
  }'
```

创建任务返回 `{task_id, status, progress, model, created}`。关键参数：

* `duration`：视频时长（秒），2\~30 连续档位，缺省 8，超限截断到最近边界；更长视频请通过编辑接口多轮拼接
* `size`：`480p` / `720p` / `1080p` 或 `宽x高`（如 `1280x720`），宽高比支持 16:9 与 9:16，其余比例用 `parameters.aspect_ratio`
* `input_reference` / `first_frame` / `last_frame`：参考图公网 URL，单次请求图片输入合计上限 30 张，超限返回 400
* `parameters`：原生上游参数透传（snake_case 优先，camelCase 兼容），如 `aspect_ratio` / `resolution` / `duration_seconds` / `generate_audio` / `seed`；不支持 `fps`、`sample_count`、4K 分辨率

`completed` 后响应携带 `result_url`（有时效性，建议及时下载或走 `/content`）、`duration`、`completed_at`。

## 通用响应信息

| 字段                 | 位置                | 用途            |
| ------------------ | ----------------- | ------------- |
| `usage`            | 响应体               | token 统计      |
| `metadata.billing` | 响应体 / 流式 metadata | JoyToken 计费信息 |
| `X-Request-ID`     | 请求头               | 日志和排障关联       |