# 使用文档：API 接入

llmgate 兼容 OpenAI `/v1` 调用方式。业务侧只需要替换 API Key 和 base_url，模型名仍使用平台公开的标准模型名。

## 入口信息

| 项目 | 值 |
|---|---|
| API 入口 | `https://api.llmgate.shop/v1` |
| 文本示例模型 | `doubao-seed-2-0-pro-260215` |
| 图片示例模型 | `doubao-seedream-5-0-lite` |

## API 接入流程

1. 管理员创建账号并充值：由后台管理员创建账号后完成钱包充值，所有 API Key 共用同一个用户钱包。
2. 创建 API Key：在控制台生成 sk-lg-*，业务侧使用同一个 Key 走统一鉴权。
3. 替换 base_url：当前 API 入口为 https://api.llmgate.shop/v1。
4. 发送测试请求：用公开模型名发起一次最小请求，再到控制台调用记录核对 requestId、token 和扣费。

## API 支持接口

业务系统只需要接入下列 OpenAI-compatible 入口；控制台、后台和支付回调使用的 `/api/*` 属于站内接口，不作为第三方集成入口。

| 方法 | 路径 | 鉴权 | 用途 |
|---|---|---|---|
| `GET` | `/v1/models` | 无需 API Key | 返回模型列表、可调用状态、能力、产品渠道和当前价格，供业务系统接入前查询。 |
| `POST` | `/v1/chat/completions` | Bearer sk-lg-* | 业务系统主调用入口，兼容 OpenAI Chat Completions 的 model、messages、stream 和 tools。 |
| `POST` | `/v1/images/generations` | Bearer sk-lg-* | 图片生成入口，JSON 请求。不同图片模型支持的 size、resolution、参考图和返回格式不一样，按下方模型参数表接入。 |
| `POST` | `/v1/images/edits` | Bearer sk-lg-* | 图片编辑入口，multipart/form-data 请求，支持 image 原图、mask、prompt、model、n、size、response_format、output_format、output_compression、input_fidelity、partial_images 和 stream。 |
| `POST` | `/v1/videos/generations` | Bearer sk-lg-* | 视频生成同步入口，JSON 请求；当前异步视频线路（Seedance、HappyHorse）只要返回可轮询 `task_id` 就统一进入 `status=running`，即使响应里已经带 usage 也不会立刻成功扣费；只有拿到可交付视频 URL 才能是成功终态。 |
| `GET` | `/v1/videos/generations/{task_id}` | Bearer sk-lg-* | 查询同步视频入口返回的公开视频任务状态；异步视频线路（Seedance、HappyHorse）的 `{task_id}` 兼容上游 task_id 和本次 request_id。响应同样统一顶层 `id`、`task_id`、`status` 和 `video_urls`。已知还在生成中的任务遇到一次上游轮询 5xx 会继续返回 `status=running`，只有 `status=failed` 才代表最终失败。异步任务不要用这个接口，改用 /tasks/{taskId}。 |
| `POST` | `/v1/images/generations/async` | Bearer sk-lg-* | 图片生成异步入口，复用同步图片生成 JSON 请求体和对应模型参数规则；创建成功返回 202 和 generation.task。 |
| `GET` | `/v1/images/generations/tasks/{taskId}` | Bearer sk-lg-* | 查询图片生成异步任务状态和结果，只返回当前 API Key 所属账户的任务。 |
| `DELETE` | `/v1/images/generations/tasks/{taskId}` | Bearer sk-lg-* | 取消尚未提交到上游的图片生成异步任务；已提交或运行中的任务会返回 409。 |
| `POST` | `/v1/images/edits/async` | Bearer sk-lg-* | 图片编辑异步入口，复用同步图片编辑 multipart/form-data 请求体；任务接口不返回 SSE，创建任务时会忽略 stream 和 partial_images。 |
| `GET` | `/v1/images/edits/tasks/{taskId}` | Bearer sk-lg-* | 查询图片编辑异步任务状态和结果，只返回当前 API Key 所属账户的任务。 |
| `DELETE` | `/v1/images/edits/tasks/{taskId}` | Bearer sk-lg-* | 取消尚未提交到上游的图片编辑异步任务；已提交或运行中的任务会返回 409。 |
| `POST` | `/v1/videos/generations/async` | Bearer sk-lg-* | 视频生成异步入口，复用同步视频生成 JSON 请求体；推荐长耗时视频任务使用。 |
| `GET` | `/v1/videos/generations/tasks/{taskId}` | Bearer sk-lg-* | 查询视频生成异步任务状态和结果，平台 worker 负责上游轮询和媒体转存。 |
| `DELETE` | `/v1/videos/generations/tasks/{taskId}` | Bearer sk-lg-* | 取消尚未提交到上游的视频生成异步任务；已提交或运行中的任务会返回 409。 |
| `GET` | `/v1/usage` | Bearer sk-lg-* | 查询当前账户自己的调用日志列表，支持按时间、request_id、模型、状态和 API Key 过滤。 |
| `GET` | `/v1/usage/{request_id}` | Bearer sk-lg-* | 按 request_id 查询单次调用的 token、扣费、状态和用户可见错误信息。 |

## 生图模型参数

生图参数按模型看，不同模型不要混用。同步 `/v1/images/generations` 和异步 `/v1/images/generations/async` 使用同一套 JSON 请求体。

### Doubao Seedream 5.0 Lite

模型名：`doubao-seedream-5-0-lite`

公开生图模型，适合常规文生图和参考图生成。当前平台标准渠道按张计费。

| 参数 | 说明 |
|---|---|
| `model` | 必填，使用当前小节的公开模型名。 |
| `prompt` | 必填，图片生成提示词，字符串。 |
| `size` | 可选。可传清晰度档位、比例或像素尺寸；平台会按当前模型的官方尺寸规则归一后再请求上游。 |
| `resolution` | 可选，平台兼容字段。传了它就按它决定清晰度档位；没传时平台从 `size` 推断。 |
| `image / reference_images / images` | 可选参考图，支持 URL 或 data URL；`image` 适合单张参考图，数组字段适合多张参考图。 |
| `use_reference_image_size` | 可选布尔值。只对 Seedream 生图生效；显式传了非空 `size` 时以 `size` 为准。未传 `size` 且带参考图时，平台读取第一张 data URL 或公网 URL 参考图宽高作为尺寸来源；缺参考图、URL 不安全或读不到宽高会返回 HTTP 400。 |
| `n` | 可选，生成张数；按实际生成张数计费。 |
| `response_format` | 可选，常用 `url` 或 `b64_json`，实际返回格式以当前线路能力为准。 |
| `watermark` | 可选，是否添加 AI 生成水印，布尔值；传 `false` 时不加水印。 |
| `size / resolution values` | `2K`、`3K`、`4K`；也可传 `1:1`、`16:9`、`9:16` 等比例或 `WIDTHxHEIGHT`。`1K` 会按平台兼容规则归一到 Seedream 可接收的尺寸。 |

- 未传 `size` 或 `resolution` 时，平台默认按 `2K` 请求。
- 自定义像素必须能归一到模型可接受的范围；不支持的 `size` 或 `resolution` 会直接返回 HTTP 400，不会扣费。

官网有但当前平台线路不开放/未确认的参数：

| 官网参数 | 当前平台线路状态 |
|---|---|
| `stream` | 官网有流式相关能力；当前 Seedream 公开线路按同步结果或异步任务推进，不承诺图片流式响应。 |
| `sequential_image_generation` | 官网有连续生图能力；当前公开 Seedream 图片线路未验收，不作为用户侧可用参数。 |
| `sequential_image_generation_options` | 官网有连续生图配置；依赖连续生图能力，当前公开线路不开放。 |
| `tools` | 官网有工具能力，例如联网搜索；当前公开 Seedream 图片线路未验收，不承诺生效。 |
| `optimize_prompt_options` | 官网有提示词优化配置；当前公开线路未验收，不开放给用户端依赖。 |

Seedream 5.0 Lite 图片生成：

```bash
curl https://api.llmgate.shop/v1/images/generations \
  -H "Authorization: Bearer sk-lg-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5-0-lite",
    "prompt": "A clean product photo of a ceramic coffee cup",
    "size": "3K",
    "image": "https://example.com/reference.png",
    "n": 1,
    "response_format": "url"
  }'
```

### Doubao Seedream 4.5

模型名：`doubao-seedream-4-5`

公开生图模型，适合高质量文生图和参考图生成。当前平台标准渠道按张计费。

| 参数 | 说明 |
|---|---|
| `model` | 必填，使用当前小节的公开模型名。 |
| `prompt` | 必填，图片生成提示词，字符串。 |
| `size` | 可选。可传清晰度档位、比例或像素尺寸；平台会按当前模型的官方尺寸规则归一后再请求上游。 |
| `resolution` | 可选，平台兼容字段。传了它就按它决定清晰度档位；没传时平台从 `size` 推断。 |
| `image / reference_images / images` | 可选参考图，支持 URL 或 data URL；`image` 适合单张参考图，数组字段适合多张参考图。 |
| `use_reference_image_size` | 可选布尔值。只对 Seedream 生图生效；显式传了非空 `size` 时以 `size` 为准。未传 `size` 且带参考图时，平台读取第一张 data URL 或公网 URL 参考图宽高作为尺寸来源；缺参考图、URL 不安全或读不到宽高会返回 HTTP 400。 |
| `n` | 可选，生成张数；按实际生成张数计费。 |
| `response_format` | 可选，常用 `url` 或 `b64_json`，实际返回格式以当前线路能力为准。 |
| `watermark` | 可选，是否添加 AI 生成水印，布尔值；传 `false` 时不加水印。 |
| `size / resolution values` | `2K`、`4K`；也可传 `1:1`、`16:9`、`9:16` 等比例或 `WIDTHxHEIGHT`。`3K` 不属于当前模型公开支持档位。 |

- 未传 `size` 或 `resolution` 时，平台默认按 `2K` 请求。
- `doubao-seedream-4-5` 不写 `3K`，避免业务侧按另一个模型的能力误传参数。

官网有但当前平台线路不开放/未确认的参数：

| 官网参数 | 当前平台线路状态 |
|---|---|
| `stream` | 官网有流式相关能力；当前 Seedream 公开线路按同步结果或异步任务推进，不承诺图片流式响应。 |
| `sequential_image_generation` | 官网有连续生图能力；当前公开 Seedream 图片线路未验收，不作为用户侧可用参数。 |
| `sequential_image_generation_options` | 官网有连续生图配置；依赖连续生图能力，当前公开线路不开放。 |
| `tools` | 官网有工具能力，例如联网搜索；当前公开 Seedream 图片线路未验收，不承诺生效。 |
| `optimize_prompt_options` | 官网有提示词优化配置；当前公开线路未验收，不开放给用户端依赖。 |

Seedream 4.5 图片生成：

```bash
curl https://api.llmgate.shop/v1/images/generations \
  -H "Authorization: Bearer sk-lg-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-4-5",
    "prompt": "A clean product photo of a ceramic coffee cup",
    "size": "4K",
    "image": "https://example.com/reference.png",
    "n": 1,
    "response_format": "url"
  }'
```

## 生视频模型参数

生视频参数同样按模型看。长耗时任务建议优先使用 `/v1/videos/generations/async`，再轮询 `/v1/videos/generations/tasks/{taskId}`。

### Doubao Seedance 2.0

模型名：`doubao-seedance-2-0`

公开生视频模型，支持文生视频、图生视频和多模态参考素材。长耗时任务建议走异步接口。

| 参数 | 说明 |
|---|---|
| `model` | 必填，使用当前小节的公开模型名。 |
| `content` | 必填，官方内容数组。至少包含一个文本提示词或一个参考素材块；参考图、视频、音频分别使用 `image_url`、`video_url`、`audio_url`。素材 URL 必须能被当前上游线路读取。 |
| `duration` | 可选，视频时长，按模型和上游当前能力取值。 |
| `ratio` | 可选，Seedance 官方画面比例枚举：`16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`21:9` 或 `adaptive`。Seedance 2.0 / 2.0 fast 不传时，平台按官方默认补齐为 `adaptive` 再提交上游，模型会根据参考素材和输入内容选择画幅；需要强制横屏、竖屏或方图时再传固定枚举。 |
| `resolution` | 可选，Seedance 官方分辨率字段，建议使用 `480p`、`720p`、`1080p` 或 `4k`；不传时按 `720p` 判档。平台额外兼容 `video_resolution`、`videoResolution` 和 `size` 作为分辨率别名，但推荐新接入只传 `resolution`。 |
| `generate_audio` | 可选，是否生成音频，布尔值。 |
| `watermark` | 可选，是否加水印，布尔值。 |
| `seed` | 可选，随机种子，整数。 |
| `return_last_frame` | 可选，是否返回尾帧，布尔值。 |
| `tools` | 可选。需要联网搜索时传 `[{"type":"web_search"}]`；不用搜索时不要传。 |

- 首尾帧用 `role: "first_frame"` / `role: "last_frame"`；普通参考图用 `role: "reference_image"`。尾帧不能单独使用，必须同时有首帧。
- 公开 `/v1/videos/generations` 和 `/v1/videos/generations/async` 当前不会代建上游素材组或素材，也不开放素材库 CRUD。API 客户只按 `content` 提交普通参考素材 URL，不要传 `asset://`、控制台素材 ID、素材组 ID、上游素材 ID、上游任务 ID 或供应商专用审核参数。网页控制台使用持久平台素材库，并在生成时按最终实际线路自动选择短期签名 URL 或隔离的上游素材副本。
- 同步入口可能直接返回视频，也可能返回上游任务；异步视频线路（Seedance、HappyHorse）会把不同上游的任务包装统一成顶层 `id`、`task_id`、`status` 和 `video_urls`。只要响应里有可轮询 task id，就按 `status=running` 返回并创建内部收口任务，即使上游同时返回 usage 也不会立即成功扣费；如果提交阶段某条异步视频上游 HTTP 200 但没有 task id 也没有视频 URL，会按 `UPSTREAM_VIDEO_RESULT_MISSING` 记当前线路失败并继续 fallback，所有候选都不可交付时才失败。已知运行中的同步视频查询遇到临时上游轮询 5xx 时继续返回 `status=running`；任务已经成功落到平台媒体后，查询优先返回平台转存后的视频地址。平台异步入口会由 worker 负责轮询、转存和结算。

官网有但当前平台线路不开放/未确认的参数：

| 官网参数 | 当前平台线路状态 |
|---|---|
| `callback_url` | 官网有回调地址；平台公开异步任务不开放客户回调，统一由平台 worker 轮询、转存和结算，客户查询 `/tasks/{taskId}`。 |

Seedance 2.0 视频生成：

```bash
curl https://api.llmgate.shop/v1/videos/generations \
  -H "Authorization: Bearer sk-lg-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0",
    "content": [
      {"type": "text", "text": "A short cinematic shot of a coffee cup on a wooden desk"},
      {"type": "image_url", "image_url": {"url": "https://example.com/reference.png"}, "role": "reference_image"}
    ],
    "duration": 5,
    "ratio": "16:9",
    "resolution": "1080p",
    "generate_audio": true,
    "watermark": false
  }'
```

Seedance 2.0 首尾帧视频生成：

```bash
curl https://api.llmgate.shop/v1/videos/generations \
  -H "Authorization: Bearer sk-lg-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0",
    "content": [
      {"type": "text", "text": "Make a smooth cinematic transition from the first image to the second image"},
      {"type": "image_url", "role": "first_frame", "image_url": {"url": "https://example.com/first-frame.png"}},
      {"type": "image_url", "role": "last_frame", "image_url": {"url": "https://example.com/last-frame.png"}}
    ],
    "duration": 5,
    "ratio": "16:9",
    "resolution": "1080p",
    "generate_audio": false,
    "watermark": false,
    "return_last_frame": true
  }'
```

### Doubao Seedance 2.0 Fast

模型名：`doubao-seedance-2-0-fast`

公开生视频模型，优先速度。请求体和 Seedance 2.0 保持同一套官方内容数组写法。

| 参数 | 说明 |
|---|---|
| `model` | 必填，使用当前小节的公开模型名。 |
| `content` | 必填，官方内容数组。至少包含一个文本提示词或一个参考素材块；参考图、视频、音频分别使用 `image_url`、`video_url`、`audio_url`。素材 URL 必须能被当前上游线路读取。 |
| `duration` | 可选，视频时长，按模型和上游当前能力取值。 |
| `ratio` | 可选，Seedance 官方画面比例枚举：`16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`21:9` 或 `adaptive`。Seedance 2.0 / 2.0 fast 不传时，平台按官方默认补齐为 `adaptive` 再提交上游，模型会根据参考素材和输入内容选择画幅；需要强制横屏、竖屏或方图时再传固定枚举。 |
| `resolution` | 可选，Seedance 官方分辨率字段，建议使用 `480p`、`720p`、`1080p` 或 `4k`；不传时按 `720p` 判档。平台额外兼容 `video_resolution`、`videoResolution` 和 `size` 作为分辨率别名，但推荐新接入只传 `resolution`。 |
| `generate_audio` | 可选，是否生成音频，布尔值。 |
| `watermark` | 可选，是否加水印，布尔值。 |
| `seed` | 可选，随机种子，整数。 |
| `return_last_frame` | 可选，是否返回尾帧，布尔值。 |

- Fast 模型不要照搬图片模型的 `prompt + image` 写法；视频请求用 `content` 数组。首尾帧同样使用 `first_frame` / `last_frame` 角色。
- 公开 `/v1/videos/generations` 和 `/v1/videos/generations/async` 当前不会代建上游素材组或素材，也不开放素材库 CRUD。API 客户只按 `content` 提交普通参考素材 URL，不要传 `asset://`、控制台素材 ID、素材组 ID、上游素材 ID、上游任务 ID 或供应商专用审核参数。网页控制台使用持久平台素材库，并在生成时按最终实际线路自动选择短期签名 URL 或隔离的上游素材副本。
- 平台当前按 output token 结算视频生成；创建阶段先返回任务状态，最终扣费等任务完成后推进。

官网有但当前平台线路不开放/未确认的参数：

| 官网参数 | 当前平台线路状态 |
|---|---|
| `callback_url` | 官网有回调地址；平台公开异步任务不开放客户回调，统一由平台 worker 轮询、转存和结算，客户查询 `/tasks/{taskId}`。 |
| `tools` | 官网同系列存在联网搜索工具写法；Fast 线路当前未验收，不写入公开支持参数。需要联网搜索时优先使用 `doubao-seedance-2-0`。 |

Seedance 2.0 Fast 视频生成：

```bash
curl https://api.llmgate.shop/v1/videos/generations \
  -H "Authorization: Bearer sk-lg-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-fast",
    "content": [
      {"type": "text", "text": "A short cinematic shot of a coffee cup on a wooden desk"},
      {"type": "image_url", "image_url": {"url": "https://example.com/reference.png"}, "role": "reference_image"}
    ],
    "duration": 5,
    "ratio": "16:9",
    "resolution": "720p",
    "generate_audio": true,
    "watermark": false
  }'
```

Seedance 2.0 Fast 首尾帧视频生成：

```bash
curl https://api.llmgate.shop/v1/videos/generations \
  -H "Authorization: Bearer sk-lg-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-fast",
    "content": [
      {"type": "text", "text": "Make a smooth cinematic transition from the first image to the second image"},
      {"type": "image_url", "role": "first_frame", "image_url": {"url": "https://example.com/first-frame.png"}},
      {"type": "image_url", "role": "last_frame", "image_url": {"url": "https://example.com/last-frame.png"}}
    ],
    "duration": 5,
    "ratio": "16:9",
    "resolution": "720p",
    "generate_audio": false,
    "watermark": false,
    "return_last_frame": true
  }'
```

## 控制台视频生成首尾帧

- 在控制台打开 `视频生成`，模型选择 `doubao-seedance-2-0` 或 `doubao-seedance-2-0-fast`。
- 参考模式切到 `首尾帧`；这个模式只收图片，不接收参考视频或参考音频。
- 上传第 1 张图作为首帧；需要尾帧时再上传第 2 张图。只有尾帧、没有首帧的任务不能提交。
- 网页控制台提供持久 Seedance 素材库：上传一次后可以查询、复用、重命名和删除。原文件保存在平台私有存储，提交视频时平台才按本次最终实际线路选择短期签名 URL 或隔离的上游素材副本。用户不填写 `asset://`、素材组 ID 或上游素材 ID。

## 生成接口接入方式

- 同步生成接口保持原有 OpenAI-compatible 接入方式：请求直接等待上游返回，不创建公开异步任务，也不受异步队列影响。当前异步视频同步入口（Seedance、HappyHorse）不要求客户解析不同上游的原始任务包装，客户只依赖顶层 `id`、`task_id`、`status` 和 `video_urls`；拿到上游 task id 时一律先返回 `status=running`，最终扣费等平台拿到可交付视频后再收口。已知还在生成中的任务遇到一次上游轮询 5xx 仍保持 `status=running`，不能把临时轮询失败当成最终失败；提交阶段某条异步视频上游 HTTP 200 但没有 task id 也没有视频 URL 会按 `UPSTREAM_VIDEO_RESULT_MISSING` 记当前线路失败并继续 fallback，所有候选都不可交付时才失败，不会成功扣用户费用。
- 异步生成接口是在原路径后追加 `/async`：创建任务返回 HTTP 202，客户端拿 `id` 或 `status_url` 轮询 `/tasks/{taskId}`。
- 轮询接口只读平台任务状态，不直接打上游；排队、上游提交、视频轮询、媒体转存和最终结算都由后台 worker 推进。
- 任务状态包括 `queued`、`submitted`、`running`、`storing_media`、`succeeded`、`failed`、`expired` 和 `cancelled`；内部并发等待原因不会暴露给用户。

异步任务创建成功后返回的基础结构如下：

```json
{
  "id": "task_xxx",
  "object": "generation.task",
  "kind": "image_generation",
  "status": "queued",
  "status_url": "/v1/images/generations/tasks/task_xxx",
  "request_id": null,
  "llmgate_image": {
    "requested": {
      "model": "doubao-seedream-5-0-lite",
      "size": "3K",
      "n": 1
    },
    "standard": {
      "model": "doubao-seedream-5-0-lite",
      "size": "3k",
      "image_size_tier": "3K",
      "n": 1
    }
  },
  "result": null,
  "error": null
}
```

图片生成异步调用示例：

```bash
curl https://api.llmgate.shop/v1/images/generations/async \
  -H "Authorization: Bearer sk-lg-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5-0-lite",
    "prompt": "A clean product photo of a ceramic coffee cup",
    "size": "3K",
    "n": 1
  }'

# Use the returned id, for example task_xxx.
curl https://api.llmgate.shop/v1/images/generations/tasks/task_xxx \
  -H "Authorization: Bearer sk-lg-your-key-here"
```

## API 最小接入参数

- 请求头使用 `Authorization: Bearer sk-lg-your-key-here`。
- Python OpenAI SDK 设置 `base_url`，Node.js OpenAI SDK 设置 `baseURL`。
- 聊天补全请求发送到 `/chat/completions`，完整地址会由 base_url 拼接。
- 请求模型使用平台模型名，例如 `doubao-seed-2-0-pro-260215`。
- 调用完成后在控制台调用记录核对 `requestId`、token、扣费和产品渠道。

## 聊天视频输入

/v1/chat/completions 支持受控视频理解。公开标准 content part 使用 { "type": "video", "uri": "https://.../video.mp4", "mime_type": "video/mp4" }；内联视频使用 { "type": "video", "data": "<base64>", "mime_type": "video/mp4" }。模型必须在 `/v1/models` 的 `capabilities.video_input` 里显示支持；真实线路不支持时，平台会自动 fallback 到其它可用候选。

示例：

```bash
curl https://api.llmgate.shop/v1/chat/completions \
  -H "Authorization: Bearer sk-lg-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-pro",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "请按时间顺序描述这段视频。"},
          {"type": "video", "uri": "https://example.com/video.mp4", "mime_type": "video/mp4"}
        ]
      }
    ]
  }'
```

## 调用日志查询

调用日志查询接口使用 `Authorization: Bearer sk-lg-your-key-here` 鉴权，只返回当前 API Key 所属账户自己的日志。

`GET /v1/usage` 查询调用日志列表，支持游标分页。响应里的 `next_cursor` 用作下一页请求的 `cursor`；没有下一页时为 `null`。

| 参数 | 说明 |
|---|---|
| `start_time` | ISO 时间，按 created_at >= start_time 过滤。 |
| `end_time` | ISO 时间，按 created_at < end_time 过滤。 |
| `request_id` | 精确查询某一次调用。 |
| `model` | 按用户请求的模型名模糊查询。 |
| `status` | 按调用终态过滤，例如 success、error、timeout。 |
| `api_key_id` | 只看当前账户某把 API Key 产生的调用。 |
| `limit` | 每页条数，默认 20，最大 100。 |
| `cursor` | 上一页返回的 next_cursor，用于继续翻页。 |

`GET /v1/usage/{request_id}` 查询单条调用详情。如果这条记录不属于当前账户，返回 404。

调用记录返回字段：

| 字段 | 说明 |
|---|---|
| `request_id` | 本次调用 ID。 |
| `created_at` | 调用日志创建时间。 |
| `model` | 用户请求的平台模型名。 |
| `product_channel` | 最终落库和结算使用的产品渠道。 |
| `product_channel_route_chain` | 用户可见的产品渠道尝试链，只展示产品渠道 code。 |
| `api_key_id / api_key_name` | 本次调用使用的 API Key ID 和名称。 |
| `status` | 调用终态。 |
| `error_code / error_message` | 用户可见错误码和错误文案；成功和处理中类状态都返回 null，只有最终失败才返回错误码和错误文案。 |
| `is_stream` | 是否流式调用。 |
| `billing_mode / fixed_request_units` | 计费方式和按次计费次数。 |
| `input_tokens / output_tokens` | 输入和输出 token。 |
| `cache_read_tokens / cache_write_tokens` | 缓存读和缓存写 token；claude-* 模型记录会额外返回 cache_write_5m_tokens 和 cache_write_1h_tokens。 |
| `total_tokens` | 输入、输出、缓存读、缓存写合计。 |
| `first_byte_latency_ms / latency_ms` | 普通请求表示首包延迟和总耗时；Seedance 同步视频等异步收口记录表示提交首包和提交耗时。 |
| `charged_amount` | 本次用户扣费金额；未扣费失败请求为 0，状态异常但实际扣费的历史或边界记录返回真实扣费金额。 |
| `official_reference_amount` | 只在成功请求中按用户扣费金额和命中折扣反推官网参考金额；失败请求或缺少有效折扣时为 null。 |
| `saved_amount` | 只在成功请求中返回 max(官网参考金额 - 用户扣费, 0)；失败请求或缺少有效折扣时为 null。 |
| `currency` | 币种，跟随站点默认币种；当前环境为 CNY。 |
| `billing_discount` | 命中折扣，包含 ratio 和 source；没有可计算折扣时为 null。 |
| `llmgate_image` | 生图调用的图片参数摘要，包含 requested 客户提交参数和 standard 平台按模型规则归一后的参数；非生图记录为 null。 |
| `video_generation` | 同步视频异步收口摘要，包含 status、started_at、completed_at 和 duration_ms；任务未终态时 duration_ms 为 null；非此类视频记录为 null。 |

公开调用日志接口不返回数据库 `id`、route trace 原文、真实上游、上游凭据、内部重试链路、成本、毛利、payload、clientIp 或 userAgent。

## API 示例代码

### Python

```python
from openai import OpenAI

client = OpenAI(
    api_key="sk-lg-your-key-here",
    base_url="https://api.llmgate.shop/v1",
)

response = client.chat.completions.create(
    model="doubao-seed-2-0-pro-260215",
    messages=[{"role": "user", "content": "Hello!"}],
)

print(response.choices[0].message.content)
```

### Node.js

```ts
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-lg-your-key-here",
  baseURL: "https://api.llmgate.shop/v1",
});

const response = await client.chat.completions.create({
  model: "doubao-seed-2-0-pro-260215",
  messages: [{ role: "user", content: "Hello!" }],
});

console.log(response.choices[0].message.content);
```

### curl

```bash
curl https://api.llmgate.shop/v1/chat/completions \
  -H "Authorization: Bearer sk-lg-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seed-2-0-pro-260215",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'
```