本文档面向本站用户,介绍如何使用本站的文本、图片和视频接口,以及如何将本站接入 Codex CLI、Claude Code 等常用工具。
具体可用模型、参数范围和价格以本站控制台及模型详情页为准。
1. 开始接入
1.1 获取令牌
在本站控制台的「令牌」页面创建 API 令牌,并立即保存令牌值。令牌只在创建时完整显示,请勿将令牌提交到代码仓库或发送给他人。
所有接口都通过 HTTPS 和 Bearer Token 鉴权:
Authorization: Bearer <你的令牌>
1.2 基础地址
https://www.xingshengstudio.com
OpenAI 风格接口使用 /v1 前缀:
https://www.xingshengstudio.com/v1
1.3 验证令牌
查询当前令牌可用的模型:
curl https://www.xingshengstudio.com/v1/models \
-H "Authorization: Bearer $NEW_API_KEY"
返回模型列表即表示地址和令牌配置正确。
1.4 通用错误格式
请求失败时,接口通常返回以下格式:
{
"error": {
"message": "请求参数无效",
"type": "invalid_request_error",
"code": "..."
}
}
请根据 error.message 调整请求。普通用户收到的是不包含上游余额、上游模型名、地址、密钥和原始错误报文的安全提示;管理员在任务日志、任务详情、相应管理 API 和服务端日志中保留原始上游错误,便于排查。内部重试、渠道健康判断也始终使用原始错误分类。
任务详情和通用日志中的原始模型、实际上游模型及模型映射仅向管理员展示;普通用户只显示本站模型名。
常见状态码:
| 状态码 | 含义 |
|---|---|
400 |
请求参数错误 |
401 |
令牌无效或未提供 |
403 |
无权使用该模型或接口 |
404 |
模型、任务或文件不存在 |
429 |
请求过于频繁或额度不足 |
503 |
当前服务暂时不可用 |
2. 文本模型接入
兼容各现有工具,仅需替换base_url和api_key即可。
2.1 对话接口
最常用的 OpenAI 风格对话请求:
curl https://www.xingshengstudio.com/v1/chat/completions \
-H "Authorization: Bearer $NEW_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "<模型名>",
"messages": [{"role": "user", "content": "你好"}]
}'
需要流式输出时增加 "stream": true,并按 SSE 格式读取响应。
2.2 常用文本接口
| 能力 | 方法与路径 |
|---|---|
| 对话 | POST /v1/chat/completions |
| Responses | POST /v1/responses |
| 补全 | POST /v1/completions |
| Claude 消息 | POST /v1/messages |
| Gemini 内容生成 | POST /v1beta/models/{model}:generateContent |
| 向量 | POST /v1/embeddings |
| 重排序 | POST /v1/rerank |
| 语音合成 | POST /v1/audio/speech |
| 语音转写 | POST /v1/audio/transcriptions |
并非所有模型都支持全部接口,请以模型详情页显示的能力为准。
3. 接入 Codex CLI
Codex CLI 默认使用 Responses 接口。先在本站创建一个可使用目标文本模型的令牌,然后编辑 ~/.codex/config.toml:
model = "<文本模型名>"
model_provider = "newapi"
[model_providers.newapi]
name = "本站"
base_url = "https://www.xingshengstudio.com/v1"
env_key = "NEW_API_KEY"
wire_api = "responses"
在当前终端中设置令牌:
export NEW_API_KEY="<你的令牌>"
启动 Codex:
codex
也可以先执行一次非交互请求进行验证:
codex exec "请回复 connected"
说明:
base_url必须包含/v1。<文本模型名>必须替换为本站实际可用的模型名。- 目标模型必须支持 Responses 接口。
- 不需要再执行
codex login;令牌由env_key指定的环境变量提供。 - 如果已有自定义 provider,请合并配置,不要直接覆盖整个
config.toml。
4. 接入 Claude Code
Claude Code 使用本站的 /v1/messages 接口。先在当前终端设置站点地址和令牌:
export ANTHROPIC_BASE_URL="https://www.xingshengstudio.com"
export ANTHROPIC_AUTH_TOKEN="<你的令牌>"
启动 Claude Code:
claude
指定模型时可以运行:
claude --model "<Claude 模型名>"
也可以在 Claude Code 中使用 /model 切换模型,使用 /status 检查当前地址和认证方式。
如需长期保存配置,可写入用户级 ~/.claude/settings.json:
{
"env": {
"ANTHROPIC_BASE_URL": "https://www.xingshengstudio.com",
"ANTHROPIC_AUTH_TOKEN": "<你的令牌>"
}
}
说明:
ANTHROPIC_BASE_URL只填写站点根地址,不要添加/v1。- 不要把包含令牌的配置写入项目中会提交的
.claude/settings.json。 - 修改配置后重新启动 Claude Code。
5. 图片生成
5.1 异步图片任务
耗时较长的图片请求建议使用异步接口:先提交任务,再根据任务 ID 轮询结果。
文生图:
curl https://www.xingshengstudio.com/v1/images/tasks \
-H "Authorization: Bearer $NEW_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "<图片模型名>",
"prompt": "一只在月光下奔跑的狐狸",
"n": 1
}'
图片编辑:
curl https://www.xingshengstudio.com/v1/images/tasks \
-H "Authorization: Bearer $NEW_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "<图片模型名>",
"prompt": "把背景改成海边",
"images": ["https://example.com/input.png"]
}'
本地参考图直接使用 multipart 上传:
curl https://www.xingshengstudio.com/v1/images/tasks \
-H "Authorization: Bearer $NEW_API_KEY" \
-F model="<图片模型名>" \
-F prompt="把背景改成海边" \
-F image=@./input.png
提交成功后会立即返回任务 ID,id 与 task_id 相同:
{
"id": "task_0123456789abcdef",
"task_id": "task_0123456789abcdef",
"object": "image.task",
"model": "<图片模型名>",
"status": "queued",
"progress": "0%",
"created_at": 1784092800
}
5.2 查询图片任务
curl https://www.xingshengstudio.com/v1/images/tasks/<task_id> \
-H "Authorization: Bearer $NEW_API_KEY"
常见状态为 queued、in_progress、completed 和 failed。任务完成后,data 按顺序返回图片结果:
{
"id": "task_0123456789abcdef",
"object": "image.task",
"model": "<图片模型名>",
"status": "completed",
"progress": "100%",
"created_at": 1784092800,
"completed_at": 1784092923,
"data": [
{
"url": "https://example.com/result.png",
"index": 0
}
]
}
下载 data[].url 即可。启用对象存储时,转存地址默认有效 4 小时;如果响应包含 expires_at,请在链接过期前完成下载。
单张图片任务也可以使用以下地址下载第一张结果:
curl -L https://www.xingshengstudio.com/v1/images/tasks/<task_id>/content \
-H "Authorization: Bearer $NEW_API_KEY" \
-o result.png
任务失败时,普通用户的 error.message 为安全提示;管理员可在任务日志、任务详情及相应管理 API 中查看原始上游错误。
5.3 同步文生图
curl https://www.xingshengstudio.com/v1/images/generations \
-H "Authorization: Bearer $NEW_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "<图片模型名>",
"prompt": "一只坐在窗边的橘猫",
"n": 1,
"size": "1024x1024",
"response_format": "url"
}'
response_format为url时,从data[].url读取图片地址。response_format为b64_json时,从data[].b64_json读取 Base64 图片。
5.4 图片编辑 / 图生图
本地图片使用 multipart 直接上传:
curl https://www.xingshengstudio.com/v1/images/edits \
-H "Authorization: Bearer $NEW_API_KEY" \
-F model="<图片模型名>" \
-F prompt="把背景改成海边" \
-F image=@./input.png
JSON 请求也可以通过 images 提供参考图片地址:
{
"model": "<图片模型名>",
"prompt": "把背景改成海边",
"images": ["https://example.com/input.png"]
}
images 数组:
["https://example.com/input.png"]
该字段要求填写无需登录即可访问的绝对 http(s) 地址。本地文件请直接使用 multipart 上传。
6. 视频生成
6.1 提交视频任务
视频接口为 POST /v1/videos,支持 JSON 和 multipart 请求。
常用字段:
| 字段 | 必填 | 说明 |
|---|---|---|
model |
是 | 视频模型名 |
prompt |
否 | 提示词;prompt 与素材字段(content / images / first_frame 等)至少提供一个 |
seconds |
是 | 视频时长(整数秒,1–3600);seconds 与 duration 至少提供一个,按秒计价 |
duration |
是 | seconds 的等效字段,两者都缺会返回 seconds is required |
resolution |
否 | 如 480p、720p、1080p、4k;不传时默认 720p |
ratio |
否 | 如 16:9、9:16、1:1、3:4、4:3、21:9 |
generate_audio |
否 | 是否生成音频 |
content |
否 | 标准参考素材数组,包含 reference_image、first_frame、last_frame、reference_video、reference_audio |
images |
否 | 参考图片列表,支持公网 HTTPS URL 数组或对象数组,等效映射为参考图 |
videos |
否 | 参考视频列表,支持公网 HTTPS URL 数组或对象数组,等效映射为参考视频 |
audios |
否 | 参考音频列表,支持公网 HTTPS URL 数组或对象数组,等效映射为参考音频 |
first_frame |
否 | 首帧图片公网 HTTPS URL 或兼容字段(如 first_frame_image) |
last_frame |
否 | 尾帧图片公网 HTTPS URL 或兼容字段(如 last_frame_image) |
按分辨率计价的模型如果未开放 720p(在售分辨率中不含 720p),必须显式传入该模型支持的分辨率,否则返回参数错误;计费与分辨率无关的模型不受此限制,缺省仍按 720p 处理。
1. 纯文本生成视频
curl https://www.xingshengstudio.com/v1/videos \
-H "Authorization: Bearer $NEW_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "<视频模型名>",
"prompt": "一只猫在钢琴旁演奏",
"seconds": 5
}'
2. 通过 images / videos / audios 快捷字段传递参考素材
网关支持直接在 JSON 顶层传入 images、videos、audios 字段,网关会自动完成参数归一化与各上游渠道的协议适配,无需手动构造 content 数组:
curl https://www.xingshengstudio.com/v1/videos \
-H "Authorization: Bearer $NEW_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "<视频模型名>",
"prompt": "一只猫在海滩奔跑,动作自然连贯",
"seconds": 5,
"images": [
"https://example.com/cat1.jpg",
"https://example.com/cat2.jpg"
],
"videos": [
"https://example.com/beach_motion.mp4"
],
"audios": [
"https://example.com/bgm.mp3"
]
}'
素材字段格式说明:
images:支持字符串数组["https://..."]、单个字符串"https://...",或对象数组[{"url": "https://..."}]/[{"image_url": "https://..."}]。别名支持reference_images、image_urls、image。videos:支持字符串数组["https://..."]、单个字符串"https://...",或对象数组[{"url": "https://..."}]/[{"video_url": "https://..."}]。别名支持reference_videos、video_urls、video。audios:支持字符串数组["https://..."]、单个字符串"https://...",或对象数组[{"url": "https://..."}]/[{"audio_url": "https://..."}]。别名支持reference_audios、audio_urls、audio。- 所有传入的 URL 必须是公网无需鉴权直接可访问的
https://链接。
3. 通过标准 content 数组传递参考素材
如果使用标准契约,可通过 content 数组显式指定每种素材的角色类型:
curl https://www.xingshengstudio.com/v1/videos \
-H "Authorization: Bearer $NEW_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "<视频模型名>",
"prompt": "镜头从清晨的街道推进到窗边",
"seconds": 10,
"resolution": "720p",
"ratio": "16:9",
"generate_audio": true,
"content": [
{"type": "first_frame", "url": "https://example.com/first_frame.jpg"},
{"type": "last_frame", "url": "https://example.com/last_frame.jpg"},
{"type": "reference_image", "url": "https://example.com/ref.jpg"}
]
}'
content 数组元素格式为 {"type": "...", "url": "..."}:
type |
用途 |
|---|---|
reference_image |
普通参考图片 |
first_frame |
首帧图片(最多一个) |
last_frame |
尾帧图片(最多一个) |
reference_video |
参考视频 |
reference_audio |
参考音频 |
url 必须是无需登录即可访问的绝对 HTTPS 地址。同时包含 first_frame 和 last_frame 时走首尾帧生成视频。
4. 通过 multipart 上传本地文件
本地素材也可以直接使用 multipart 上传,网关会自动将文件保存到对象存储并转换为公网 HTTPS 地址交由上游生成:
curl https://www.xingshengstudio.com/v1/videos \
-H "Authorization: Bearer $NEW_API_KEY" \
-F model="<视频模型名>" \
-F prompt="镜头从清晨的街道推进到窗边" \
-F seconds=10 \
-F first_frame=@./first_frame.jpg \
-F last_frame=@./last_frame.jpg \
-F images=@./reference.jpg \
-F videos=@./reference.mp4 \
-F audios=@./bgm.mp3
可上传的字段支持单文件与数组形式:
| 字段名 | 素材类型 | 说明 |
|---|---|---|
first_frame |
首帧图片 | 别名:first_frame_image、first_frame_url |
last_frame |
尾帧图片 | 别名:last_frame_image、last_frame_url |
images 或 images[] |
参考图片 | 别名:image、image[]、reference_images 等 |
videos 或 videos[] |
参考视频 | 别名:video、video[]、reference_videos 等 |
audios 或 audios[] |
参考音频 | 别名:audio、audio[]、reference_audios 等 |
6.2 查询视频任务
提交后保存返回的任务 ID,然后轮询任务状态:
curl https://www.xingshengstudio.com/v1/videos/<task_id> \
-H "Authorization: Bearer $NEW_API_KEY"
常见状态为 queued、in_progress、completed 和 failed。任务完成后,url、video_url 和 result_url 返回同一个下载地址:
{
"id": "task_0123456789abcdef",
"object": "video",
"model": "<视频模型名>",
"status": "completed",
"progress": "100%",
"url": "https://example.com/result.mp4",
"video_url": "https://example.com/result.mp4",
"result_url": "https://example.com/result.mp4"
}
启用对象存储时,转存地址默认有效 4 小时;如果响应包含 expires_at,请在链接过期前下载。也可以通过本站鉴权接口下载视频:
curl -L https://www.xingshengstudio.com/v1/videos/<task_id>/content \
-H "Authorization: Bearer $NEW_API_KEY" \
-o output.mp4
任务失败时,普通用户的 error.message 为安全提示;管理员可在任务日志、任务详情及相应管理 API 中查看原始上游错误。