# 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}` |

## 文本模型

- `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-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`。不同模型支持的输入形态不同，以上游实际能力和控制台日志快照为准。

## 文本请求示例

```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、模型名、产品渠道、扣费金额和上游快照是排障与对账依据。
- 账号创建、充值和权限开通由管理员处理。