# StarChasing API 文档

## 当前入口

| 项目 | 值 |
| --- | --- |
| Base URL | `https://api.starchasing.ai/v1` |
| API Key | `Authorization: Bearer sk-lg-your-key-here` |
| 鉴权前缀 | `sk-lg-*` |

StarChasing 使用 OpenAI-compatible API 形态。请求里的 `model` 必须填写平台公开模型名，不要填写上游厂商内部模型名。

## API 接入流程

1. 管理员创建账号并完成钱包充值。
2. 登录控制台，在 API Keys 页面创建 `sk-lg-*` API Key。
3. 把 SDK 或 HTTP 请求的 base URL 改成 `https://api.starchasing.ai/v1`。
4. 先调用 `GET /v1/models` 确认当前账号可见模型，再发起真实请求。
5. 通过 `GET /v1/usage` 或 `GET /v1/usage/{request_id}` 查看调用日志和扣费快照。

## API 支持接口

| 场景 | 接口 |
| --- | --- |
| 模型列表 | `GET /v1/models` |
| 文本对话 | `POST /v1/chat/completions` |
| 图片生成 | `POST /v1/images/generations` |
| 图片异步生成 | `POST /v1/images/generations/async` |
| 图片编辑异步生成 | `POST /v1/images/edits/async` |
| 视频生成 | `POST /v1/videos/generations` |
| 视频异步生成 | `POST /v1/videos/generations/async` |
| 视频任务查询 | `GET /v1/videos/generations/tasks/{taskId}` |
| 调用日志列表 | `GET /v1/usage` |
| 调用日志详情 | `GET /v1/usage/{request_id}` |

按模型名模糊搜索调用日志时，如果没有指定精确的 `request_id`，必须同时传入 ISO 时间格式的 `start_time` 和 `end_time`，且范围不超过 24 小时；可以查询任意历史日期。缺少时间返回 400 / `USAGE_MODEL_SEARCH_TIME_RANGE_REQUIRED`，范围过大返回 400 / `USAGE_MODEL_SEARCH_TIME_RANGE_TOO_WIDE`。此类搜索按账户共享额度，同一账户的所有 API Key 共用额度；代码默认滚动 60 秒最多接受 60 次，Redis 可用且租约持续续期时同账户并发准入上限为 1、全站为 4，实际阈值以所在站点 App 配置为准。超限返回 429 / `USAGE_MODEL_SEARCH_RATE_LIMITED` 和 `Retry-After`；领取名额时 Redis 不可用或限流配置无效，仅此类搜索返回 503 / `USAGE_MODEL_SEARCH_UNAVAILABLE` 和 `Retry-After`。租约持续续期失败而旧查询未结束时，并发数可能短暂超过准入上限。普通列表、精确请求 ID 查询和单条详情不受这组搜索限制。

## 文本模型

- `glm-5`
- `glm-5.1`
- `glm-5.2`
- `deepseek-v3.2`
- `deepseek-v4-flash`
- `deepseek-v4-pro`

文本模型使用 `POST /v1/chat/completions`。常用参数包括 `model`、`messages`、`stream`、`temperature`、`top_p`、`max_tokens`、`tools` 和 `response_format`。先用普通文本请求验证模型可用，再开启工具调用或 JSON 输出。

## 图片模型

- `doubao-seedream-5-0-lite`
- `doubao-seedream-4-5`

图片生成使用 `POST /v1/images/generations` 或异步接口。常用参数包括 `model`、`prompt`、`size`、`n` 和 `response_format`。异步任务返回任务 ID，按任务查询接口轮询结果。

## 视频模型

- `doubao-seedance-2-5`
- `doubao-seedance-2-0`
- `doubao-seedance-2-0-fast`
- `happyhorse-1.1-t2v`
- `happyhorse-1.1-i2v`
- `happyhorse-1.1-r2v`
- `happyhorse-1.0-t2v`
- `happyhorse-1.0-i2v`
- `happyhorse-1.0-r2v`
- `happyhorse-1.0-video-edit`

视频生成使用 `POST /v1/videos/generations` 或异步接口。常用参数包括 `model`、`prompt`、`resolution`、`duration`、`aspect_ratio`、`first_frame_url`、`last_frame_url`、`reference_images` 和 `video_url`。不同模型支持的输入形态不同，以上游实际能力和控制台日志快照为准。

### Seedance 参考素材边界

- 网页控制台提供持久 Seedance 素材库：上传一次后可以查询、复用、重命名和删除。原文件保存在平台私有存储，提交视频时平台才按本次最终实际线路选择短期签名 URL 或隔离的上游素材副本。用户不填写 `asset://`、素材组 ID 或上游素材 ID。
- 公开 `/v1/videos/generations` 和 `/v1/videos/generations/async` 都按 `content` 接收参考素材 URL。需要上游素材库的 Seedance 线路会在取得本次线路凭据后、提交视频前由平台准备参考素材；普通线路继续使用 URL。异步请求在返回 202 前保存参考素材，任务终态后清理；特殊线路的同步请求只在本次提交期间临时保存。公开 API 不开放持久素材库 CRUD；不要传 `asset://`、控制台素材 ID、素材组 ID、上游素材 ID、上游任务 ID 或供应商专用审核参数。Seedance 视频不支持 `stream=true`，请按任务状态轮询。网页控制台另提供持久平台素材库。

## 文本请求示例

```bash
curl https://api.starchasing.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-lg-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5",
    "messages": [
      { "role": "user", "content": "Write one short product tagline." }
    ],
    "stream": false
  }'
```

## 模型列表示例

```bash
curl https://api.starchasing.ai/v1/models \
  -H "Authorization: Bearer sk-lg-your-key-here"
```

## 调用日志示例

```bash
curl "https://api.starchasing.ai/v1/usage?limit=20" \
  -H "Authorization: Bearer sk-lg-your-key-here"
```

## 注意事项

- API Key 只使用 StarChasing 控制台生成的 `sk-lg-*`，不要使用上游厂商 Key。
- 所有公开示例都使用 `https://api.starchasing.ai/v1`。
- 控制台调用记录里的 request ID、模型名、产品渠道、扣费金额和上游快照是排障与对账依据。
- 账号创建、充值和权限开通由管理员处理。