本文档面向调用方，介绍如何使用本站统一网关，以及图片、视频和文件上传接口。

1. 开始接入

1.1 获取令牌

在本站控制台的「令牌」页面创建 API 令牌，并记录令牌值。令牌只在创建时完整显示，请妥善保管。

所有接口都使用 HTTPS，并通过 Bearer Token 鉴权：

Authorization: Bearer <你的令牌>

1.2 基础地址

把 <本站地址> 替换为管理员提供的网关地址。接口统一使用 /v1 前缀：

https://<本站地址>/v1

1.3 通用错误格式

请求失败时，接口返回统一的错误对象：

{
  "error": {
    "message": "请求参数无效",
    "type": "invalid_request_error",
    "code": "..."
  }
}

2. 文本模型接入

本站兼容常见的 OpenAI 风格接口。最常用的对话请求如下：

curl https://<本站地址>/v1/chat/completions \
  -H "Authorization: Bearer $NEW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<模型名>",
    "messages": [{"role": "user", "content": "你好"}]
  }'

常用接口：

具体模型名以本站控制台显示为准。

3. 图片生成

3.1 同步文生图

curl https://<本站地址>/v1/images/generations \
  -H "Authorization: Bearer $NEW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<图片模型名>",
    "prompt": "一只坐在窗边的橘猫",
    "n": 1,
    "size": "1024x1024",
    "response_format": "url"
  }'

响应中的 data[].url 是图片地址；如果使用 response_format: "b64_json"，则从 data[].b64_json 读取 Base64 图片。

3.2 图片编辑 / 图生图

使用 multipart 上传原图：

curl https://<本站地址>/v1/images/edits \
  -H "Authorization: Bearer $NEW_API_KEY" \
  -F model="<图片模型名>" \
  -F prompt="把背景改成海边" \
  -F image=@./input.png

也可以在 JSON 请求中引用已经上传到本站的文件地址，见「文件上传」。

3.3 异步图片任务

适合耗时较长的生图请求。先提交任务，再轮询任务状态：

curl https://<本站地址>/v1/images/tasks \
  -H "Authorization: Bearer $NEW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"<图片模型名>","prompt":"一只在月光下奔跑的狐狸","n":1}'

返回 id 或 task_id 后轮询：

curl https://<本站地址>/v1/images/tasks/<task_id> \
  -H "Authorization: Bearer $NEW_API_KEY"

任务完成后，响应中的 data[].url 可直接下载结果；也可以使用：

GET /v1/images/tasks/{task_id}/content

常见状态：queued、in_progress、completed、failed。

4. 视频生成

4.1 提交视频任务

视频接口支持 JSON 或 multipart。multipart 示例：

curl https://<本站地址>/v1/videos \
  -H "Authorization: Bearer $NEW_API_KEY" \
  -F model="<视频模型名>" \
  -F prompt="一只猫在钢琴旁演奏" \
  -F seconds=5

使用 JSON 时示例：

curl https://<本站地址>/v1/videos \
  -H "Authorization: Bearer $NEW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"<视频模型名>","prompt":"一只猫在钢琴旁演奏","seconds":5}'

4.2 查询和下载结果

提交后记录返回的任务 ID：

curl https://<本站地址>/v1/videos/<task_id> \
  -H "Authorization: Bearer $NEW_API_KEY"

任务完成后下载视频：

curl -L https://<本站地址>/v1/videos/<task_id>/content \
  -H "Authorization: Bearer $NEW_API_KEY" \
  -o output.mp4

常见状态：queued、in_progress、completed、failed。按秒计费的模型需要提供 seconds 或 duration。

5. 文件上传

文件接口用于上传图片、视频和音频，再把返回的地址作为后续请求的素材引用。

5.1 上传文件

curl https://<本站地址>/v1/files \
  -H "Authorization: Bearer $NEW_API_KEY" \
  -F purpose=vision \
  -F file=@./reference.png

成功后会返回文件 ID 和 content_url：

{
  "id": "file-0123456789abcdef0123456789abcdef",
  "object": "file",
  "bytes": 20480,
  "filename": "reference.png",
  "purpose": "vision",
  "mime_type": "image/png",
  "content_url": "/v1/files/file-0123456789abcdef0123456789abcdef/content"
}

5.2 下载文件

curl -L https://<本站地址>/v1/files/<file_id>/content \
  -H "Authorization: Bearer $NEW_API_KEY" \
  -o reference.png

5.3 在生成请求中引用

将 content_url 拼成完整 URL，填入对应接口支持的图片或视频素材字段：

{
  "model": "<图片或视频模型名>",
  "prompt": "参考这张图片生成新的画面",
  "image": "https://<本站地址>/v1/files/<file_id>/content"
}

单文件上限、保留时间和支持的媒体类型以本站当前配置为准。文件按账号隔离，其他账号无法使用你的 file_id。