返回首页 接入文档

本文档面向本站用户,介绍如何使用本站的文本、图片和视频接口,以及如何将本站接入 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"

说明:

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": "<你的令牌>"
  }
}

说明:

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"
  }'

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"
    ]
  }'

素材字段格式说明:

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 中查看原始上游错误。