跳到导航

API 指南

JoyToken 面向开发者提供 OpenAI 兼容和 Anthropic 兼容的模型接口。

通用 API

Base URL 使用 环境 中的 JOY_TOKEN_API_BASE_URL。

接口认证用途
GET /api/v1/models无公开模型列表
GET /api/v1/models/metaBearer 或 X-API-Key目录筛选元数据
GET /api/v1/pricingBearer 或 X-API-Key面向客户的档位兑换价格

模型描述可通过可选的 locale 查询参数指定语言:locale=zh 返回中文,locale=en 返回英文;不传时默认返回英文。

curl -sS "https://api-staging.joytokens.ai/api/v1/models?locale=zh"

选择协议接口

项目值
接口POST /openai/v1/chat/completions
Base URLhttps://api-staging.joytokens.ai/openai/v1
认证Authorization: Bearer $JOY_TOKEN_API_KEY
响应内容choices[0].message.content

Responses 接口为 POST /openai/v1/responses。input 支持字符串或 message input items;非流式文本位于 output[0].content[0].text。

curl -N -sS -X POST "https://api-staging.joytokens.ai/openai/v1/responses" \
-H "Authorization: Bearer $JOY_TOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "auto",
"input": "用一句话解释 JoyToken。",
"instructions": "保持简洁。",
"max_output_tokens": 256,
"stream": false
}'

图片生成接口为 POST /openai/v1/images/generations。model 必须为 auto,prompt 为必填字段。n、size、quality、style、response_format 等图片选项会透传给所选 Provider;请省略 Provider 特有选项,除非所有候选图片模型都支持该选项。

图片生成仅支持非流式响应。不要传 stream: true,也不要按 SSE 消费此接口:保持请求连接,直到 JoyToken 在生成完成后一次性返回完整的 application/json。生成图片位于 data;根据 response_format 从 data[0].url 或 data[0].b64_json 读取结果。

curl -sS -X POST "https://api-staging.joytokens.ai/openai/v1/images/generations" \
-H "Authorization: Bearer $JOY_TOKEN_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Request-ID: image-$(date +%s%3N)" \
-d '{
"model": "auto",
"prompt": "A neon JoyToken logo on a black background",
"n": 1,
"size": "1024x1024"
}'
{
"created": 1793395200,
"data": [
{
"url": "https://example.com/generated.png",
"revised_prompt": "A neon JoyToken logo on a black background"
}
]
}
curl -N -sS -X POST "https://api-staging.joytokens.ai/openai/v1/chat/completions" \
-H "Authorization: Bearer $JOY_TOKEN_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Request-ID: test-$(date +%s%3N)" \
-d '{
"model": "auto",
"messages": [
{ "role": "user", "content": "你好,帮我测试一下网关链路" }
],
"temperature": 0.7,
"max_tokens": 1024,
"stream": false
}'

不要在同一个请求里同时传 Authorization 和 X-API-Key。如果两个都存在,当前网关会优先读取 X-API-Key。

视频生成 / 视频编辑

视频接口为异步三段式任务模型,适用模型 Doubao-Seedance-2.5(model 省略时为 auto,由网关在视频模型池中自动路由):

步骤接口说明
创建生成任务POST /openai/v1/videos文生视频 / 图生视频 / 首尾帧,返回 task_id(202)
创建编辑任务POST /openai/v1/videos/edits多视频拼接,响应与生成任务一致
轮询状态GET /openai/v1/videos/{task_id}200,编辑任务与生成任务共用
下载成片GET /openai/v1/videos/{task_id}/content302 跳转到成片 URL

生成入口支持三种方式:文生视频(仅 prompt,必填)、图生视频(input_reference 单图或多图,prompt 可省略)、首尾帧生视频(first_frame / last_frame,prompt 可省略)。生成入口不接受 input_video;多视频拼接请走编辑入口,编辑入口必须至少携带一种媒体输入(input_reference / first_frame / last_frame / input_video)。

curl -sS -X POST "https://api-staging.joytokens.ai/openai/v1/videos" \
-H "Authorization: Bearer $JOY_TOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "auto",
"prompt": "一只橘猫在雨中的东京街头奔跑,电影感运镜",
"duration": 8,
"size": "1280x720"
}'

创建任务返回 {task_id, status, progress, model, created}。关键参数:

  • duration:视频时长(秒),2~30 连续档位,缺省 8,超限截断到最近边界;更长视频请通过编辑接口多轮拼接
  • size:480p / 720p / 1080p 或 宽x高(如 1280x720),宽高比支持 16:9 与 9:16,其余比例用 parameters.aspect_ratio
  • input_reference / first_frame / last_frame:参考图公网 URL,单次请求图片输入合计上限 30 张,超限返回 400
  • parameters:原生上游参数透传(snake_case 优先,camelCase 兼容),如 aspect_ratio / resolution / duration_seconds / generate_audio / seed;不支持 fps、sample_count、4K 分辨率

completed 后响应携带 result_url(有时效性,建议及时下载或走 /content)、duration、completed_at。

通用响应信息

字段位置用途
usage响应体token 统计
metadata.billing响应体 / 流式 metadataJoyToken 计费信息
X-Request-ID请求头日志和排障关联