API 参考

OpenAI 兼容 API

所有接口与 OpenAI 官方 /v1/* 协议完全兼容，只需把 base_url 指向我们即可。

通用约定

Base URL	https://xjjuhe.site/v1
鉴权头	Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx
请求体	application/json; charset=utf-8
时区	UTC（响应里所有时间戳为秒级 Unix 时间）
字符集	UTF-8
HTTP/2	支持，自动协商

所有接口都需要在 Authorization 头携带 Bearer sk-jp-xxx 鉴权。其余 HTTP 头与 OpenAI 一致：无需特殊配置。

错误处理

所有错误响应使用与 OpenAI 一致的结构：HTTP 状态码 + JSON body{ error: { message, type, code } }。

json

{
  "error": {
    "message": "API Key 不存在或已被删除",
    "type": "invalid_api_key",
    "code": null
  }
}

常见状态码

状态码	type	含义
400	invalid_request_error	请求体无效（缺字段、JSON 格式错等）
401	invalid_api_key	API Key 缺失、格式错或已删除
403	invalid_request_error	请求权限、账户状态或访问范围不满足要求
403	insufficient_quota	账户余额不足、API Key 额度已用完，或余额不足以支付本次请求预估费用
403	invalid_api_key	Key 已禁用 / IP 不在白名单 / 模型不在白名单
404	model_not_found	模型不存在或已下架
429	rate_limit_exceeded	超出速率限制（短时间高并发）
500	api_error	平台内部错误，建议稍后重试
502	upstream_error	当前请求较多，请稍后重试
503	upstream_error	当前请求较多，请稍后重试

Chat Completions

POST

https://xjjuhe.site/v1/chat/completions

多轮对话生成。传入 messages 历史，模型返回 assistant 消息。支持 GPT、Claude、Gemini、DeepSeek、通义、Kimi 等所有 chat 类模型。

请求参数

字段	类型	是否必填	说明
model	string	必填	模型 name，如 gpt-4o-mini、claude-3-5-sonnet
messages	array	必填	对话历史。每条 {role: system\|user\|assistant\|tool, content: string}
stream	boolean	可选	默认 false。true 时返回 text/event-stream 流
temperature	number	可选	采样温度 0~2，默认 1。值越大输出越随机
top_p	number	可选	核采样 0~1。与 temperature 二选一
max_tokens	number	可选	生成的最大 token 数
stop	string\|array	可选	遇到该字符串时停止生成
presence_penalty	number	可选	-2.0~2.0，鼓励引入新话题
frequency_penalty	number	可选	-2.0~2.0，避免重复用词
tools	array	可选	Function Calling 工具定义（OpenAI 标准格式）
tool_choice	string\|object	可选	"auto"/"none" 或指定特定工具
user	string	可选	终端用户标识，平台会记录在日志中

请求示例

bash

curl https://xjjuhe.site/v1/chat/completions \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "system", "content": "你是一个简洁的助手。"},
      {"role": "user", "content": "用一句话介绍北京"}
    ],
    "temperature": 0.7,
    "max_tokens": 200,
    "stream": false
  }'

响应示例（非流式）

json

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "北京是中国的首都，拥有 3000 多年历史的政治文化中心。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 22,
    "total_tokens": 47
  }
}

响应示例（流式 SSE）

响应 Content-Type: text/event-stream。每条事件以 data: 开头，最后一条为 [DONE]。

text

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","created":1700000000,"model":"gpt-4o-mini","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc","choices":[{"index":0,"delta":{"content":"北京"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc","choices":[{"index":0,"delta":{"content":"是"},"finish_reason":null}]}

...

data: {"id":"chatcmpl-abc","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

GPT-5.5/GPT-5.6 接入示例

gpt-5.5 与 gpt-5.6-sol 是 OpenAI 兼容 chat 模型。 OpenAI SDK、Chatbox、Cherry Studio 等普通聊天客户端请使用 /v1/chat/completions 端点调用。二者使用同一套 OpenAI 兼容接口，仅 model 参数不同。

字段	类型	是否必填	说明
Base URL	string	必填	https://xjjuhe.site/v1
Endpoint	string	必填	/v1/chat/completions
model	string	必填	填写实际模型名，如 gpt-5.5 或 gpt-5.6-sol
API Key	string	必填	使用本平台控制台生成的用户 API Key，不要填写上游供应商密钥
stream	boolean	可选	建议先用 false 测试，成功后再开启 true

bash

curl https://xjjuhe.site/v1/chat/completions \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      {"role": "user", "content": "你好，用一句话介绍你自己"}
    ],
    "temperature": 0.7,
    "max_tokens": 1024,
    "stream": false
  }'

CC Switch / Codex 的 Agent 模式通常会调用 /v1/responses 并携带工具定义。gpt-5.5 仅建议用于普通聊天/代码问答；如需文件读取、项目分析、工具调用，请改用后台标记为支持 Tools 的 Agent 兼容模型。

计费说明

按 token 计费：total = (prompt_tokens / 1M) × 输入价 + (completion_tokens / 1M) × 输出价
调用失败（HTTP 4xx/5xx 或上游错误）不扣费，仍记录日志
流式调用按完整流读完后的 usage 字段计费（OpenAI 流末尾会回传 usage）
每个模型的精确价格见定价页

Images Generations

POST

https://xjjuhe.site/v1/images/generations

文生图 / 图生图。gpt-image-2 和 gpt-image-2.5 使用异步任务模式：提交接口立即返回任务 ID；n 支持 1-4，平台会为每张图提交一个独立异步任务，调用方再通过查询接口获取最终图片 URL。请求结构兼容 OpenAI Images API，并提供 reference_images 参考图平台扩展。如需图生图（以图改图），可在请求中附带 reference_images 参数，或使用 Images Edits 端点上传原图。

reference_images 不是 OpenAI 官方 /images/generations 字段，而是平台扩展。调用方始终使用本页公开端点；平台会按实际渠道转换参考图字段并提交异步任务。无需直接调用供应商内部任务端点，但需要用任务查询接口轮询结果。

GPT Image 2.5

调用方仍使用本站公开的 /v1/images/generations，平台会在内部提交异步任务。提交成功后使用响应中的 id 或 task_id 查询结果。

字段	类型	是否必填	说明
model	string	必填	固定填写 gpt-image-2.5
prompt	string	必填	图片生成或编辑指令，最大 4000 字符
n	number	可选	1-4；每张图片对应一个独立异步任务
size	string	可选	1024x1024 / 1280x720 / 720x1280 / 1248x832 / 832x1248 / 1152x864 / 864x1152 / 1120x896 / 896x1120 / 1456x624
image_size	string	可选	分辨率档位，仅支持 1K；不能与 size 同时使用
resolution	string	可选	image_size 的兼容别名，仅支持 1K；两个字段不要重复填写
reference_images	string[]	可选	参考图 URL 或完整 Data URL，最多 8 张
response_format	string	可选	异步模式仅支持 url

bash

curl https://xjjuhe.site/v1/images/generations \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5",
    "prompt": "白色背景上的高端香水产品摄影",
    "n": 1,
    "size": "1024x1024"
  }'

GPT Image 2.5 当前仅提供 1K 输出。推荐直接填写支持的 size；若使用 image_size 或 resolution，值只能是 1K，且不能再填写 size。

gpt-image-2.5-flare 在本站同样按 1K 模式接入，请求和查询方式与 gpt-image-2.5 相同；本站暂不开放该模型的 2K / 4K 档位。

Nano Banana 2

字段	类型	是否必填	说明
prompt	string	必填	最大 10000 字符
aspect_ratio	string	可选	1:1 / 9:16 / 16:9 / 3:4 / 4:3 / 3:2 / 2:3 / 5:4 / 4:5 / 21:9 / auto
reference_images	string[]	可选	同步接口参考图；URL 或完整 Data URL，最多 8 张，单张最大 10MB
images	string[]	可选	异步 /v1/videos 接口参考图；规则同 reference_images

bash

curl https://xjjuhe.site/v1/images/generations \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano_banana_2",
    "prompt": "将参考图转换成油画风格",
    "aspect_ratio": "16:9",
    "reference_images": ["https://example.com/reference.jpg"]
  }'

bash

# 提交任务
curl https://xjjuhe.site/v1/videos \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano_banana_2",
    "prompt": "金色阳光下的宁静湖面",
    "aspect_ratio": "16:9",
    "images": []
  }'

# 使用提交响应中的 id 或 task_id 查询
curl https://xjjuhe.site/v1/videos/task_xxxxxxxxxxxxx \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx"

请求参数

字段	类型	是否必填	说明
model	string	必填	图像模型 name，如 gpt-image-2 或 gpt-image-2.5；具体可用模型以 /v1/models 返回为准
prompt	string	必填	普通图片模型最大 4000 字符；Nano Banana 2 最大 10000 字符
n	number	可选	gpt-image-2 / gpt-image-2.5 异步模式支持 1-4；平台会为每张图提交一个独立任务，每个 task_id 对应 1 张图
size	string	可选	像素尺寸；gpt-image-2 中与 aspect_ratio 二选一，gpt-image-2.5 支持的尺寸见上表
aspect_ratio	string	可选	GPT Image 2 / Nano Banana 2 宽高比；auto / 1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3 / 5:4 / 4:5 / 21:9
quality	string	可选	standard 或 hd（仅部分模型支持 hd）
style	string	可选	仅部分 OpenAI 兼容模型支持；gpt-image-2 通常不需要填写
response_format	string	可选	gpt-image-2 异步模式仅支持 url，不支持 b64_json
reference_images	string[]	可选	平台扩展。GPT Image 2 / Nano Banana 2 最多 8 个 URL/Data URL；普通模型最多 4 个公网 URL
images	string[]	可选	兼容上游字段，等同 reference_images；建议新接入优先使用 reference_images

提交任务

bash

curl https://xjjuhe.site/v1/images/generations \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "保持参考图人物主体不变，转换成油画风格",
    "n": 4,
    "size": "1024x1024",
    "reference_images": ["https://example.com/reference.jpg"]
  }'

当 n=1 时响应为单个图片任务；当 n=2..4 时响应为任务列表，客户端需要分别轮询每个 task_id。

json

{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "model": "gpt-image-2",
  "object": "image",
  "status": "queued",
  "progress": 0,
  "created": 1700000000,
  "created_at": 1700000000
}

json

{
  "object": "image.task.list",
  "model": "gpt-image-2",
  "status": "queued",
  "n": 4,
  "data": [
    {
      "id": "task_xxxxxxxxxxxxx",
      "task_id": "task_xxxxxxxxxxxxx",
      "model": "gpt-image-2",
      "object": "image",
      "status": "queued",
      "progress": 0,
      "created": 1700000000,
      "created_at": 1700000000
    },
    {
      "id": "task_yyyyyyyyyyyyy",
      "task_id": "task_yyyyyyyyyyyyy",
      "model": "gpt-image-2",
      "object": "image",
      "status": "queued",
      "progress": 0,
      "created": 1700000000,
      "created_at": 1700000000
    }
  ]
}

查询结果

GET

https://xjjuhe.site/v1/images/generations/{task_id}

bash

curl https://xjjuhe.site/v1/images/generations/task_xxxxxxxxxxxxx \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx"

json

{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "model": "gpt-image-2",
  "object": "image",
  "status": "completed",
  "progress": 100,
  "created": 1700000000,
  "created_at": 1700000000,
  "completed_at": 1700000060,
  "url": "https://cdn.juhepintai.com/img/abc.png",
  "image_url": "https://cdn.juhepintai.com/img/abc.png",
  "data": [
    {
      "url": "https://cdn.juhepintai.com/img/abc.png"
    }
  ]
}

查询接口同时支持 /v1/images/generations/{task_id} 和 /v1/videos/{task_id}。完成后优先读取 url 或 image_url；data[0].url 用于兼容 OpenAI Images 结果结构。

GPT Image 2 错误处理

HTTP	error.code	客户端处理
400	invalid_image_size	使用支持的尺寸后重试
400	invalid_image_parameter	修正 error.param 指示的参数
400	invalid_image_prompt	修改提示词
400	content_policy_violation	修改提示词或参考图
429	image_rate_limited	指数退避重试
503	image_model_unavailable	稍后重试，客户端无法通过改参数解决
502	image_service_error	稍后重试

客户端应根据 HTTP 状态码和 error.code 判断处理方式，不要解析 error.message。400 表示请求需要修改； 429、502、503 表示提交阶段的临时问题，应使用指数退避，且不要并发重复提交同一图片任务。

gpt-image-2 和 gpt-image-2.5 不会同步等待最终图片。提交成功只代表任务进入队列；建议客户端每 2-5 秒查询一次任务状态，直到 completed 或 failed。重复查询不会重复扣款或退款。

计费说明

gpt-image-2 和 gpt-image-2.5 的 n 支持 1-4；平台会拆成多个独立任务，每个任务固定 1 张图，提交时按任务数逐张预扣费用
任务完成后正式扣费；任务失败会退还预扣，不会产生费用
重复查询同一个 task_id 不会重复扣费

Images Edits（图生图）

POST

https://xjjuhe.site/v1/images/edits

以图改图。上传一张参考图 + 文字描述，生成修改后的新图片。请求必须使用 multipart/form-data 格式，图片通过 image 字段以二进制文件上传。请求格式兼容 OpenAI Images Edits 协议；平台可能在内部转换为实际渠道支持的参考图和异步任务协议。

如果你已有参考图的公网 URL，也可以直接使用 Images Generations 接口的 reference_images 平台扩展参数，无需上传文件。

请求参数（multipart/form-data）

字段	类型	是否必填	说明
model	string	必填	图像模型 name，如 gpt-image-2
prompt	string	必填	描述目标图片的自然语言（上限 4000 字符）
image	file	必填	参考图片文件（二进制），支持 PNG/JPEG/WEBP，上限 10MB
n	number	可选	生成张数，默认 1，最大 8
size	string	可选	1024x1024 / 1024x1792 / 1792x1024 等
aspect_ratio	string	可选	Nano Banana 2 宽高比
quality	string	可选	standard 或 hd
response_format	string	可选	url 或 b64_json，默认 url

请求示例

bash

curl https://xjjuhe.site/v1/images/edits \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -F model="gpt-image-2" \
  -F prompt="把背景换成海边日落，保持人物不变" \
  -F image=@photo.png \
  -F size="1024x1024"

响应示例

json

{
  "created": 1700000000,
  "data": [
    {
      "url": "https://cdn.juhepintai.com/img/edited-abc.png",
      "b64_json": null
    }
  ]
}

上传的参考图会临时存储在服务器上，上游处理完成后 10 分钟 自动删除。异步图像任务同样适用 120 秒超时，请相应设置客户端超时时间。

计费说明

与文生图相同：按张计费，total = n × 模型单价
上游失败 0 张产出时不扣费

Videos Generation（视频生成）

视频生成是异步任务，分两步调用：提交任务 → 轮询结果。生成通常需要 2-5 分钟，建议每 3-5 秒轮询一次。支持文生视频和图生视频两种模式；不同模型对参考图语义可能不同。

① 提交任务

POST

https://xjjuhe.site/v1/videos

同时支持 multipart/form-data 和 application/json 两种请求格式。

字段	类型	是否必填	说明
model	string	必填	视频模型，如 veo_3_1-fast-fl
prompt	string	必填	描述视频内容的自然语言（上限 4000 字符）
size	string	可选	视频尺寸，默认 1280x720。横版: 1280x720 / 1920x1080；竖版: 720x1280 / 1080x1920
input_reference	file/url/base64	可选	图生视频参考素材（multipart 模式，重复传入）。模型不同对参考素材语义可能不同
images	string[]	可选	图生视频参考素材（JSON 模式）。URL 或 base64 字符串数组，等同重复传入 input_reference
prompt_extend	string	可选	补充描述 / 扩展提示词

VEO

VEO 模型必须上传参考图后才能生成视频。JSON 请求使用 images 数组； multipart/form-data 请求重复传 input_reference 字段。veo_3_1-fast-fl 参考图模式适合首尾帧，1 张图作为首帧，2 张图作为首帧和尾帧。

Omni

Omni 使用同一组 /v1/videos 异步接口。当前推荐模型为 omni_flash-10s，模型名已包含质量、时长和分辨率规格。提交成功只代表任务已创建，推荐使用响应里的 id 查询最终结果。

字段	类型	是否必填	说明
model	string	必填	固定填 omni_flash-10s，或填平台为你开通的 Omni 模型别名
prompt	string	必填	视频内容描述，建议写清主体、动作、场景、镜头和风格
size	string	可选	推荐 1280x720 或 720x1280；高清规格按模型开通情况使用
images	string[]	可选	JSON 模式参考图/视频 URL 数组，最多 7 项，必须是公网可访问直链
input_reference	file/url	可选	multipart 模式重复传入参考图或本地视频文件，最多 7 项

Omni 文生视频 — JSON 示例

bash

curl https://xjjuhe.site/v1/videos \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "omni_flash-10s",
    "prompt": "一只可爱的小猫在月球表面奔跑，背景是地球，电影质感",
    "size": "1280x720"
  }'

Omni 参考图 — JSON 示例

bash

curl https://xjjuhe.site/v1/videos \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "omni_flash-10s",
    "prompt": "根据参考图生成一段 10 秒产品展示视频，镜头缓慢推进",
    "size": "1280x720",
    "images": [
      "https://example.com/ref-1.jpg",
      "https://example.com/ref-2.jpg"
    ]
  }'

Omni 参考图 URL — multipart 示例

bash

curl https://xjjuhe.site/v1/videos \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -F model="omni_flash-10s" \
  -F prompt="根据参考图生成一段 10 秒产品展示视频，镜头缓慢推进" \
  -F size="1280x720" \
  -F input_reference="https://example.com/ref-1.jpg" \
  -F input_reference="https://example.com/ref-2.jpg"

Omni 参考图或参考视频最多 7 项。图片/视频 URL 必须是直链，不能是网页地址、需要登录的地址或带防盗链的地址。多个 URL 或 Base64 参考项推荐使用 JSON 的 images 数组； JSON 请求中不要使用 input_reference。本地图片或视频文件只能用 multipart/form-data 的input_reference 字段上传。 Omni 当前按参考图集合生成，不支持 Veo 风格的“首帧 + 尾帧”专用模式。

Omni 图生视频 / 参考图验证方法

准备 1-2 个公网可访问的图片直链，浏览器打开该链接应直接显示图片。
用上面的 JSON 示例提交任务，确认响应里返回 id。
用 GET /v1/videos/{id} 每 3-5 秒查询一次。
返回 status=completed 且包含 video_url 即验证通过。
如果返回服务错误，优先检查图片 URL 是否公网可访问、是否为直链、数量是否超过 7 项。

Sora

Sora 使用同一组 /v1/videos 异步接口。当前模型为 sora-2-12s，提交成功后返回任务 id和上游 task_id，最终视频需要继续查询任务状态获取。

字段	类型	是否必填	说明
model	string	必填	固定填 sora-2-12s，或填平台为你开通的 Sora 模型别名
prompt	string	必填	视频内容描述，建议写清主体、动作、场景、镜头、风格和画面比例
size	string	必填	视频尺寸，如 1280x720、1920x1080、720x1280、1080x1920
images	string[]	可选	JSON 模式参考图 URL 数组。用于图生视频，图片必须是公网可访问直链
input_reference	file/url	可选	multipart 模式参考图字段。用于上传本地图片或传入图片 URL

Sora 文生视频 — JSON 示例

bash

curl https://xjjuhe.site/v1/videos \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2-12s",
    "prompt": "一只橘猫在月球表面奔跑，背景是地球，电影质感",
    "size": "1280x720"
  }'

Sora 图生视频 — JSON 示例

bash

curl https://xjjuhe.site/v1/videos \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2-12s",
    "prompt": "让参考图中的人物在城市街道上自然行走，镜头缓慢跟拍",
    "size": "1280x720",
    "images": [
      "https://example.com/reference.jpg"
    ]
  }'

Sora 图生视频 — multipart 示例

bash

curl https://xjjuhe.site/v1/videos \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -F model="sora-2-12s" \
  -F prompt="让参考图中的人物在城市街道上自然行走，镜头缓慢跟拍" \
  -F size="1280x720" \
  -F input_reference="https://example.com/reference.jpg"

Sora 的 images 和 input_reference都是参考图入口，二选一使用即可。图片 URL 必须能被服务器直接访问；不要传需要登录的网页地址、防盗链地址或非图片直链。返回 status=completed 且包含video_url 才表示生成完成。

文生视频 — multipart/form-data 示例

bash

curl https://xjjuhe.site/v1/videos \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -F model="sora-2-12s" \
  -F prompt="一只橘猫在月球表面奔跑，背景是地球，电影质感" \
  -F size="1920x1080"

文生视频 — JSON 示例

bash

curl https://xjjuhe.site/v1/videos \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2-12s",
    "prompt": "一只橘猫在月球表面奔跑，背景是地球，电影质感",
    "size": "1920x1080"
  }'

图生视频 — 首尾帧示例

传 1 张图 → AI 以此作为首帧生成视频；传 2 张图 → 首帧+尾帧，AI 生成中间过渡动画。

bash

# 图生视频（multipart/form-data，参考图）
curl https://xjjuhe.site/v1/videos \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -F model="veo_3_1-fast-fl" \
  -F prompt="两张图片之间的过渡动画" \
  -F size="1280x720" \
  -F input_reference="https://example.com/first-frame.jpg" \
  -F input_reference="https://example.com/last-frame.jpg"

# 图生视频（JSON，用 images 字段）
curl https://xjjuhe.site/v1/videos \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo_3_1-fast-fl",
    "prompt": "两张图片之间的过渡动画",
    "size": "1280x720",
    "images": [
      "https://example.com/first-frame.jpg",
      "https://example.com/last-frame.jpg"
    ]
  }'

提交响应示例

json

{
  "id": "cm1234567890",
  "task_id": "task_zgUBKXVW6YhJkXPvuTJ2Y0jaLnycfEu9",
  "model": "veo_3_1-fast-fl",
  "object": "video.task",
  "status": "submitted",
  "progress": 0,
  "created_at": 1700000000
}

② 查询任务状态

GET

https://xjjuhe.site/v1/videos/:id

推荐用提交时返回的 id 查询；task_id 主要用于任务排查。当 status 为 completed 时，video_url 字段即为最终视频下载链接。

查询请求示例

bash

curl https://xjjuhe.site/v1/videos/cm1234567890 \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx"

查询响应 — 生成中

json

{
  "id": "cm1234567890",
  "task_id": "task_zgUBKXVW6YhJkXPvuTJ2Y0jaLnycfEu9",
  "model": "veo_3_1-fast-fl",
  "object": "video.task",
  "status": "processing",
  "progress": 45,
  "created_at": 1700000000
}

查询响应 — 已完成

json

{
  "id": "cm1234567890",
  "task_id": "task_zgUBKXVW6YhJkXPvuTJ2Y0jaLnycfEu9",
  "model": "veo_3_1-fast-fl",
  "object": "video.task",
  "status": "completed",
  "progress": 100,
  "video_url": "https://videos-us3.ss2.life/video/xxxxx.mp4",
  "created_at": 1700000000,
  "completed_at": 1700001000
}

查询响应 — 失败

json

{
  "id": "cm1234567890",
  "task_id": "task_zgUBKXVW6YhJkXPvuTJ2Y0jaLnycfEu9",
  "model": "veo_3_1-fast-fl",
  "object": "video.task",
  "status": "failed",
  "progress": 0,
  "fail_reason": "内容违规",
  "created_at": 1700000000
}

任务状态流转

submitted→processing→completed/failed

可用尺寸

尺寸	方向	分辨率
1280x720	横版	720p
1920x1080	横版	1080p
720x1280	竖版	720p
1080x1920	竖版	1080p

视频生成平均耗时 2-5 分钟。建议客户端每 3-5 秒轮询一次，避免过于频繁请求导致限流。

计费说明

按次计费：提交时预扣，成功后正式结算，失败自动退款
视频 URL 有时效，请尽快下载保存
图生视频与文生视频计费相同（按模型单价）

数字人

数字人接口用于客户自己的系统调用。常见流程是：上传图片或视频素材，创建数字人模板或克隆任务，再用驱动音频生成口播视频。驱动音频可以上传得到 file_id，也可以先用声音样本创建声音克隆得到 voice_id，再用 voice_id + text 合成 audio_url。模板、克隆、配音和视频生成都是异步任务，提交成功后需要继续轮询查询结果；文件上传则必须确认状态为 active 后才能使用。

创建类接口必须传 Idempotency-Key。同一次上传或任务重试应保留原 key 和原参数，避免超时后重复创建和重复计费。修改文件或任务参数时使用新 key，不能把幂等键当作文件内容去重工具。

数字人计费：首次成功新增一个形象或一个声音收 ¥80，包含首套 1 个形象 + 1 个声音；之后新增形象或声音各收 ¥80。已有形象/声音生成配音和视频免费，上传、查询、同一幂等请求重试以及失败任务不新增收费。网页控制台与用户 API 使用同一账号计费状态。

通用规则

Base URL	https://xjjuhe.site/v1
鉴权	Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx
模型名	digital-human
主流程	声音克隆 voice_id → 文案合成 audio_url → 数字人视频生成
任务类型	异步任务，创建后轮询查询结果
轮询建议	每 5-10 秒查询一次，不要高频轮询
上传方式	/files：平台代传上游 OSS；/uploads：客户直传平台 COS
COS 上传 URL	签名 PUT 地址，默认有效 120 分钟；与上游 OSS 签名无关
素材大小	image 20MB / voice 100MB / driving audio 300MB / avatar video 300MB / ASR audio 500MB / ASR video 1GB
文案长度	No character cap by default; request body limit still applies
并发保护	Per API key active task limit defaults to 5

1. 上传素材

POST

https://xjjuhe.site/v1/digital-human/files

字段	类型	是否必填	说明
file	file	必填	音频、图片或视频素材文件
purpose	string	可选	用途标记，例如 voice_clone / video_driving_audio / avatar_image / video_source / asr

图片和短音频推荐先上传素材并使用返回的 file_id 创建任务。本地大视频建议先放到 OSS/COS/CDN，使用可公网匿名下载的 video_url 或 audio_url，不要把本站 /uploads 临时路径当作推荐链路。

此入口继续接收 multipart/form-data。平台内部向上游申请上传地址、 PUT 文件到 OSS，再确认上传完成；只有返回 active 后才可使用文件 ID。客户无需直接调用上游 upload-intents，也不需要持有上游密钥。上传超时请使用原幂等键和相同文件重试，不要立即换 key 重新上传。

upstream_upload_not_completed 表示上传尚未确认完成，沿用原文件和原幂等键重试；会话过期、上传失败和参数冲突有独立错误码，不能将所有 409 都当成重复请求。若返回 upstream_upload_transport_unavailable，请联系平台处理上传服务故障。此时不要反复新建克隆任务；COS 直传本身仍可用，但后续任务的自动同步也需要平台代传服务。

上传人像图片

bash

curl https://xjjuhe.site/v1/digital-human/files \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: upload-image-001" \
  -F purpose="avatar_image" \
  -F file=@portrait.jpg

上传真人视频素材

bash

curl https://xjjuhe.site/v1/digital-human/files \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: upload-video-001" \
  -F purpose="video_source" \
  -F file=@avatar-source.mp4

上传声音样本

bash

curl https://xjjuhe.site/v1/digital-human/files \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: upload-voice-001" \
  -F purpose="voice_clone" \
  -F file=@voice-sample.wav

上传驱动音频

bash

curl https://xjjuhe.site/v1/digital-human/files \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: upload-audio-001" \
  -F purpose="video_driving_audio" \
  -F file=@speech.wav

上传转写音频/视频

bash

curl https://xjjuhe.site/v1/digital-human/files \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: upload-asr-audio-001" \
  -F purpose="asr" \
  -F file=@speech.wav

Direct upload to COS

POST

https://xjjuhe.site/v1/digital-human/uploads

字段	类型	是否必填	说明
kind	string	可选	image / voice / audio / video / asr
filename	string	可选	original filename
content_type	string	可选	for example video/mp4 or audio/mpeg
size	number	可选	expected file size in bytes

The signed upload URL is valid for DIGITAL_HUMAN_UPLOAD_URL_EXPIRES_MINUTES=120. Upload with the returned upload_url and exact Content-Type, then call complete. Direct upload does not return an upstream file_id; after complete, use the returned image_url, video_url, or audio_url in the create APIs. For ASR video uploads, pass the returned URL as audio_url to the ASR endpoint.

bash

curl https://xjjuhe.site/v1/digital-human/uploads \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: direct-upload-video-001" \
  -d '{
    "kind": "video",
    "filename": "avatar-source.mp4",
    "content_type": "video/mp4",
    "size": 31457280
  }'

bash

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: video/mp4" \
  --data-binary @avatar-source.mp4

POST

https://xjjuhe.site/v1/digital-human/uploads/:upload_id/complete

bash

curl https://xjjuhe.site/v1/digital-human/uploads/upload_xxx/complete \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{}'

json

{
  "id": "upload_xxx",
  "task_id": "upload_xxx",
  "kind": "file",
  "upload_kind": "video",
  "status": "active",
  "file_id": null,
  "video_url": "https://cdn.example.com/digital-human/avatar-source.mp4",
  "cos_video_url": "https://cdn.example.com/digital-human/avatar-source.mp4",
  "content_type": "video/mp4",
  "size": 31457280
}

以上 /uploads 是平台 COS 直传，不是上游 OSS 上传会话。 COS 完成后返回公开素材 URL，不返回上游文件 ID；两类上传的 ID、签名地址、有效期和完成接口不能混用。视频首帧可按 kind=image 直传 COS，完成后把返回的 image_url 用作 first_frame_url。

使用本账号已完成上传的本站 COS URL 时，平台会在创建任务前自动同步素材到上游存储，将主素材转换为上游 file_id，并同步视频真实首帧。网页与 API 使用同一流程，客户仍传原 COS URL。其他外部 URL 原样转发，仍须符合上游域名白名单和素材要求。自动同步不新增收费；若返回 503 / upstream_media_not_ready，表示同步尚未完成、任务尚未提交，预扣暂时保留，请使用原幂等键和相同参数重试。

2. 声音克隆

POST

https://xjjuhe.site/v1/digital-human/voices/clones

字段	类型	是否必填	说明
audio_url	string	可选	公网可下载的声音样本 URL
file_id	string	可选	用 purpose=voice_clone 上传声音样本后返回的文件 ID
language	string	可选	配音目标语种：zh / en / ja / ko / de / es / fr / it / ru / yue；不传或 auto 保留原中英链路

该接口根据声音样本创建可复用音色。提交后轮询查询接口，成功时读取返回里的 voice_id，再传给文案生成语音接口。

bash

curl https://xjjuhe.site/v1/digital-human/voices/clones \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: voice-clone-001" \
  -d '{
    "file_id": "file_voice_xxx",
    "language": "ja"
  }'

普通话和英语自动使用 indextts2；日语、韩语、德语、西班牙语、法语、意大利语、俄语和粤语自动使用 ttscsv3。无需填写供应商、引擎或更换接口地址。示例创建日语配音使用的音色；文案需使用目标语言，不提供自动翻译。响应中的 voice_engine 和 voice_language 会随任务查询保留。

3. 查询声音克隆任务

GET

https://xjjuhe.site/v1/digital-human/voices/clones/:task_id

bash

curl https://xjjuhe.site/v1/digital-human/voices/clones/task_xxx \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx"

4. 文案生成语音

POST

https://xjjuhe.site/v1/digital-human/audio/speech

字段	类型	是否必填	说明
voice_id	string	必填	已就绪音色 ID；多语言 ttscsv3 音色须先在本平台克隆成功
text	string	必填	需要数字人播报的文案
speed	number	可选	语速，范围 0.5–2，默认 1
language	string	可选	与克隆相同的目标语种；省略时沿用当前账号已记录音色的语言，未记录的旧音色保留原方式

该接口用于把文案合成为驱动音频。提交成功后轮询查询接口，成功时读取返回里的 audio_url，再把它传给图片数字人或视频数字人的生成接口。

bash

curl https://xjjuhe.site/v1/digital-human/audio/speech \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: audio-speech-001" \
  -d '{
    "voice_id": "voice_xxx",
    "text": "こんにちは。ご利用ありがとうございます。",
    "speed": 1,
    "language": "ja"
  }'

切换到另一声音引擎的语言时，须先用相同参考录音重新克隆，不能把旧引擎 voice_id 直接用于新引擎。同属 ttscsv3 的已支持语种之间可复用该音色。查询仍使用原公开地址，平台按创建记录选择上游路径和原渠道凭证。未支持的语言返回 400；跨引擎配音返回 400，音色未就绪返回 409，不会因此创建付费上游任务。同一任务重试沿用原 Idempotency-Key 和语言；更改语言的新任务使用新键。

5. 查询语音合成任务

GET

https://xjjuhe.site/v1/digital-human/audio/speech/:task_id

bash

curl https://xjjuhe.site/v1/digital-human/audio/speech/task_xxx \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx"

6. 音频/视频提取文案

POST

https://xjjuhe.site/v1/digital-human/asr/transcriptions

字段	类型	是否必填	说明
audio_url	string	可选	公网可下载的音频 URL
file_id	string	可选	素材上传接口返回的音频或视频文件 ID，推荐使用 purpose=asr 上传得到的 file_id
language	string	可选	auto / zh / en / ja，默认 auto
need_denoise	boolean	可选	是否启用降噪

该接口用于把音频或视频转成文字，不是商品链接或视频链接提取文案。提交成功后轮询查询接口，成功时读取返回里的 text 字段。

bash

curl https://xjjuhe.site/v1/digital-human/asr/transcriptions \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: asr-001" \
  -d '{
    "audio_url": "https://cdn.example.com/digital-human/source.mp4",
    "language": "auto"
  }'

7. 查询文案提取任务

GET

https://xjjuhe.site/v1/digital-human/asr/transcriptions/:task_id

bash

curl https://xjjuhe.site/v1/digital-human/asr/transcriptions/task_xxx \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx"

8. 图片数字人：创建模板

POST

https://xjjuhe.site/v1/digital-human/avatars/templates

字段	类型	是否必填	说明
image_url	string	可选	公网可下载的人像图片 URL
file_id	string	可选	素材上传接口返回的文件 ID
prompt	string	可选	模板备注或生成提示

bash

curl https://xjjuhe.site/v1/digital-human/avatars/templates \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: template-001" \
  -d '{
    "file_id": "file_image_xxx",
    "prompt": "正面半身口播数字人"
  }'

9. 图片数字人：查询模板任务

GET

https://xjjuhe.site/v1/digital-human/avatars/template-tasks/:task_id

创建模板后，如果响应里返回 task_id，用该接口轮询。当状态为 succeeded 并返回 avatar_template_id 后，才能继续生成视频。

bash

curl https://xjjuhe.site/v1/digital-human/avatars/template-tasks/task_xxx \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx"

10. 图片数字人：生成视频

POST

https://xjjuhe.site/v1/digital-human/videos/generations

字段	类型	是否必填	说明
avatar_template_id	string	必填	数字人模板 ID，也兼容 template_id
audio_url	string	可选	公网可下载的驱动音频 URL
file_id	string	可选	素材上传接口返回的音频文件 ID
prompt	string	可选	视频生成提示
sample_steps	number	可选	采样步数，默认 2

bash

curl https://xjjuhe.site/v1/digital-human/videos/generations \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: image-video-001" \
  -d '{
    "avatar_template_id": "avatar_xxx",
    "audio_url": "https://example.com/speech.mp3",
    "prompt": "自然口播",
    "sample_steps": 2
  }'

11. 图片数字人：查询视频任务

GET

https://xjjuhe.site/v1/digital-human/videos/generations/:task_id

bash

curl https://xjjuhe.site/v1/digital-human/videos/generations/task_xxx \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx"

视频数字人流程

如果客户已经录制了真人视频素材，可以上传取得文件 ID，或使用 COS/CDN 的公网 video_url。创建克隆任务时还必须提供该视频真实第 0 帧的图片 URL，克隆成功后用返回的 avatar_template_id 和驱动音频生成视频。

创建视频数字人克隆任务

POST

https://xjjuhe.site/v1/digital-human/video-avatars/clones

字段	类型	是否必填	说明
video_url	string	可选	公网可下载的真人视频 URL
file_id	string	可选	上传视频素材返回的文件 ID
first_frame_url	string	必填	原始视频真实第 0 帧的公网图片 URL；不能用其他肖像或任意封面代替
source_duration_seconds	number	可选	原始视频时长，单位秒，必须大于 0；建议提供
avatar_profile	string	可选	仅支持 fineturbo 快速版，省略时使用快速版
prompt	string	可选	克隆提示或备注

bash

curl https://xjjuhe.site/v1/digital-human/video-avatars/clones \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: clone-video-avatar-001" \
  -d '{
    "video_url": "https://cdn.example.com/digital-human/avatar.mp4",
    "first_frame_url": "https://cdn.example.com/digital-human/avatar-first-frame.jpg",
    "source_duration_seconds": 61.2,
    "avatar_profile": "fineturbo",
    "prompt": "正脸清晰，适合口播"
  }'

video_url 与 file_id 二选一，不会替代必填的 first_frame_url。以 URL 提供的视频和首帧图片都应可被上游公开下载。本平台仅提供快速版，克隆和后续生成均使用 fineturbo。

查询视频数字人克隆任务

GET

https://xjjuhe.site/v1/digital-human/video-avatars/clones/:task_id

克隆成功后，响应里会返回可用于生成视频的 avatar_template_id；duration_seconds 表示克隆模板视频的时长。创建受理成功不代表模板已经可用。

bash

curl https://xjjuhe.site/v1/digital-human/video-avatars/clones/task_xxx \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx"

查询视频数字人模板

GET

https://xjjuhe.site/v1/digital-human/video-avatars/:template_id

生成视频数字人视频

POST

https://xjjuhe.site/v1/digital-human/video-avatars/generations

字段	类型	是否必填	说明
avatar_template_id	string	必填	视频数字人模板 ID，也兼容 template_id
avatar_profile	string	可选	仅支持 fineturbo 快速版；省略时仍须使用快速版模板
audio_url	string	可选	公网可下载的驱动音频 URL
file_id	string	可选	上传音频素材返回的文件 ID
prompt	string	可选	视频生成提示
loop_mode	string	可选	本地兼容字段；视频素材按上游默认 pingpong 方式往复播放
start_frame	number	可选	起始帧，需小于 end_frame
end_frame	number	可选	结束帧，需大于 start_frame

bash

curl https://xjjuhe.site/v1/digital-human/video-avatars/generations \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: video-avatar-generation-001" \
  -d '{
    "avatar_template_id": "avatar_xxx",
    "audio_url": "https://example.com/speech.mp3",
    "avatar_profile": "fineturbo",
    "prompt": "自然口播",
    "loop_mode": "pingpong",
    "start_frame": 0,
    "end_frame": 240
  }'

查询视频数字人生成任务

GET

https://xjjuhe.site/v1/digital-human/video-avatars/generations/:task_id

bash

curl https://xjjuhe.site/v1/digital-human/video-avatars/generations/task_xxx \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx"

状态说明

processing->succeeded/failed

任务可返回 queued、processing、succeeded、failed 或 canceled；失败或取消后不再继续等待，当前不提供取消任务接口。当查询结果状态为 succeeded 且包含 video_url 时，表示视频已生成完成。生成结果链接可能有时效，建议客户尽快下载保存。

任务失败原因

查询 HTTP 200 仅表示查询成功，仍须检查任务 status。失败任务返回固定说明 message 和分类 failure_code，页面与 API 使用相同分类；上游原始错误不直接公开。

upstream_face_frames_insufficient: 上游未检测到足够的有效人脸画面；请联系平台核查视频解码和人脸检测结果，不等于原视频时长为零或素材已被证明不合格
upstream_media_decode_failed: 上游无法解码素材，需核查格式和解码结果
upstream_media_fetch_failed: 上游读取素材失败，需核查访问权限和链接有效期
upstream_permission_denied: 渠道缺少业务授权，请联系管理员
upstream_authentication_failed: 渠道鉴权失败，请联系管理员
upstream_insufficient_balance: 上游额度不足，请联系管理员
upstream_rate_limited: 明确限流或繁忙；联系平台确认后再决定如何重试
upstream_task_canceled: 任务已取消
upstream_task_failed: 具体原因待查，请提供任务编号联系平台

failed 是终态，原幂等键重放只返回原结果，不会重新执行。不要使用失败任务分配的模板生成视频，也不要盲目换键重建。历史任务缺少具体诊断时不再统一解释为繁忙；原有失败退款和首套名额规则不变。

重试、权限与 Webhook

提交超时不等于任务未创建；有任务 ID 时先查询，无任务 ID 时使用原幂等键和原参数重试。
409 / idempotency_in_progress 表示原请求在处理；idempotency_parameter_conflict 表示同键改参，应恢复原参数。
503 / upstream_submission_unknown 表示受理结果待确认。保留原素材、参数和幂等键，按 Retry-After 退避重试；预扣暂时保留，勿换键重复创建。
503 / upstream_media_not_ready 表示 COS 素材同步待恢复，尚未提交克隆或生成任务。沿用原 COS URL、原参数和原幂等键；素材归属、类型或大小明确不符时会拒绝并退款。
失败响应带 x-idempotency-finalized: true 才表示原请求已确认拒绝且账务收口，不表示创建成功。登录失效、限流等未确认终态的错误，以及退款待恢复时，仍须保留原键。
联系平台时提供 UTC 请求时间、幂等键和错误中的 error.request_id（也可读取响应头 x-request-id），不要发送明文 API Key。
文件为 active、音色克隆为 succeeded、模板可用后，才能进入下一步；不同用户或项目的资源 ID 不能随意复用。
平台 API Key 的 digital-human 权限与上游项目的上传、音色、配音和数字人业务权限是两层校验；渠道健康测试通过不代表所有业务均已开通。
上游故障可能被平台转换为统一错误；排查需结合平台调用日志，不能假设上游 HTTP 状态码会原样返回。
本次适配不提供客户 Webhook，也未启用上游回调接收。请继续轮询任务查询接口；上游验签头、签名算法和通知报文待补齐后再评估接入。
历史文件和任务不批量覆盖；切换上游地址不代表原项目的音色、模板和任务自动迁移。

计费说明

素材上传和查询不扣费；已有素材生成配音、视频也不扣费。
首次新增形象或声音按首套价格计费，首套包含 1 个形象 + 1 个声音；后续新增形象、声音分别按后台价格计费。
素材新增费用在任务提交前预扣，只有任务成功终态结算；失败会释放占位并退回预扣。
首套仍在创建时，其他新增会返回 digital_human_bundle_pending，请先查询原任务。受理结果未确认或结算暂时失败时保留原预扣，以原请求或终态查询恢复，不重复扣款或退款。
余额为零或 API Key 额度用完仍可执行免费上传、查询、已有素材复用及已预扣请求恢复；新增收费仍须余额和额度充足，账号与模型权限限制仍有效。
同一用户、素材类型和 Idempotency-Key 只会产生一次素材收费占位；历史已成功素材不追溯收费。
图片和短音频可优先使用素材上传返回的 file_id；本地大视频建议使用 COS/CDN 公网直链，避免本站 uploads 链接受带宽、超时或防盗链影响。
API Key 需要开通 digital-human 模型权限，否则会返回无权限错误。

商品/社媒解析

跨平台商品数据提取。传入商品链接（或分享文案中的 URL），返回结构化的标题、描述、图片、价格等信息。支持 5 个平台，每个平台单独的端点，格式统一、使用简单。

平台	端点	方法	说明
🛒 虾皮 Shopee	/v1/parse/shopee	POST	东南亚电商，支持翻译
📦 亚马逊 Amazon	/v1/parse/amazon	GET	全球站点，支持 ASIN 直查
📕 小红书 XHS	/v1/parse/xhs	POST	笔记/搜索/店铺/分类四种模式
🎵 抖音 Douyin	/v1/parse/douyin	POST	抖音商品链接（支持短链）
📹 视频号 Channels	/v1/parse/wechat-channels	POST	视频号分享链接，返回标题、封面、视频直链和互动数据
🎬 Douyin 文案提取	/v1/extractions	POST	异步提取抖音文案、音频转写和分析结果
📷 Instagram	/v1/parse/instagram	POST	帖子/Reel 媒体解析

🛒 虾皮 Shopee

POST

https://xjjuhe.site/v1/parse/shopee

解析 Shopee 商品页面，返回标题、描述、图片、规格属性。可选 lang 参数一次性翻译为目标语言。

字段	类型	是否必填	说明
url	string	必填	Shopee 商品链接，需带 i.<shop_id>.<item_id> 格式
lang	string	可选	翻译目标语言：zh-CN / en / ja / ko / th / vi 等。不传则不翻译
timeout	number	可选	抓取超时秒数，默认 15，最大 60

请求示例

bash

curl https://xjjuhe.site/v1/parse/shopee \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://shopee.tw/product-name-i.123.456789",
    "lang": "zh-CN"
  }'

响应示例

json

{
  "success": true,
  "platform": "shopee",
  "data": {
    "title": "商品标题（已翻译为中文）",
    "description": "商品描述...",
    "images": ["https://...jpg", "https://...jpg"],
    "attributes": [{"name": "品牌", "value": "xxx"}, ...],
    "breadcrumb": "类目 > 子类目",
    "brand": "品牌名",
    "url": "https://shopee.tw/..."
  },
  "elapsed_ms": 3200
}

📦 亚马逊 Amazon

GET

https://xjjuhe.site/v1/parse/amazon

解析 Amazon 商品页面。支持 URL 或 ASIN 直查，可选翻译。推荐使用 GET + Query 参数，也兼容 POST JSON 调用。

字段	类型	是否必填	说明
url	string	可选	亚马逊商品链接（与 asin 二选一）
asin	string	可选	Amazon 标准 ASIN 编号，如 B0DXXXXX
marketplace	string	可选	站点：us / uk / de / jp / ca 等，默认自动检测
translate	string	可选	翻译目标语言：zh-CN / en / ja 等
nocache	boolean	可选	设为 true 跳过缓存，强制重新抓取

请求示例

bash

curl "https://xjjuhe.site/v1/parse/amazon?url=https://www.amazon.com/dp/B0XXXXX&translate=zh-CN" \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx"

响应示例

json

{
  "success": true,
  "platform": "amazon",
  "data": {
    "title": "商品标题",
    "price": "$29.99",
    "images": ["https://m.media-amazon.com/...jpg"],
    "features": ["特点1", "特点2"],
    "description": "详细描述...",
    "rating": "4.5",
    "reviews_count": 1234
  }
}

📕 小红书 XHS

POST

https://xjjuhe.site/v1/parse/xhs

小红书商品/笔记解析。支持四种模式：笔记解析（默认）、关键词搜索、店铺商品、分类浏览。

字段	类型	是否必填	说明
url	string	可选	商品/笔记链接（note/shop/category 模式必填）
keyword	string	可选	搜索关键词（search 模式必填）
type	string	可选	模式：note（默认）/ search / shop / category
limit	number	可选	返回数量上限，默认 20，最大 200

请求示例（笔记解析）

bash

curl https://xjjuhe.site/v1/parse/xhs \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.xiaohongshu.com/goods-detail/xxxxx"
  }'

请求示例（关键词搜索）

bash

# 关键词搜索模式
curl https://xjjuhe.site/v1/parse/xhs \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "连衣裙 夏季",
    "type": "search",
    "limit": 20
  }'

响应示例

json

{
  "success": true,
  "platform": "xhs",
  "data": {
    "source_type": "note",
    "source_value": "https://...",
    "elapsed_seconds": 5.2,
    "count": 1,
    "products": [
      {
        "product_id": "xxx",
        "name": "商品名称",
        "price": "¥199",
        "desc_short": "简短描述",
        "main_images": ["https://...jpg"],
        "seller_name": "店铺名"
      }
    ]
  },
  "elapsed_ms": 5200
}

🎵 抖音 Douyin

POST

https://xjjuhe.site/v1/parse/douyin

解析抖音商品链接，支持短链（v.douyin.com）和完整链接。返回商品标题、价格、图片等。

字段	类型	是否必填	说明
url	string	必填	抖音商品链接（短链或完整链接均可）

请求示例

bash

curl https://xjjuhe.site/v1/parse/douyin \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://v.douyin.com/xxxxx/"
  }'

响应示例

json

{
  "success": true,
  "platform": "douyin",
  "data": {
    "title": "商品标题",
    "price": "¥99.00",
    "images": ["https://...jpg"],
    "description": "详细描述...",
    "shop_name": "店铺名称"
  },
  "elapsed_ms": 4500
}

📹 视频号 Channels

POST

https://xjjuhe.site/v1/parse/wechat-channels

解析视频号分享链接，返回标题、封面、视频直链、图集、解密字段和互动数据。也支持传 oid + nid，同时传入时会优先按 id 解析。

字段	类型	是否必填	说明
url	string	可选	视频号分享链接
oid	string	可选	视频号对象 id，需要和 nid 同时传
nid	string	可选	视频号节点 id，需要和 oid 同时传

请求示例

bash

curl https://xjjuhe.site/v1/parse/wechat-channels \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://channels.weixin.qq.com/..."
  }'

响应示例

json

{
  "success": true,
  "platform": "wechat-channels",
  "data": {
    "title": "视频标题",
    "type": "video",
    "typeLabel": "视频",
    "coverUrl": "https://...jpg",
    "videoUrl": "https://...mp4",
    "encryptedUrl": "https://...",
    "encrypted": false,
    "images": [],
    "decodeKey": "713555357",
    "stats": {
      "likeCount": 2,
      "commentCount": 0,
      "favCount": 2,
      "forwardCount": 20
    }
  },
  "elapsed_ms": 3200
}

📷 Instagram

POST

https://xjjuhe.site/v1/parse/instagram

解析 Instagram 帖子/Reel，提取媒体文件（图片/视频）、文案、作者信息等。

字段	类型	是否必填	说明
url	string	必填	Instagram 帖子或 Reel 链接

请求示例

bash

curl https://xjjuhe.site/v1/parse/instagram \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.instagram.com/reel/xxxxx/"
  }'

响应示例

json

{
  "success": true,
  "platform": "instagram",
  "data": {
    "type": "reel",
    "caption": "帖子文案...",
    "media_urls": ["https://...mp4"],
    "thumbnail": "https://...jpg",
    "author": "username",
    "likes": 12345
  }
}

通用说明

商品解析依赖上游爬虫，单次请求通常耗时 3-15 秒（取决于平台响应速度）。请将 HTTP 超时设为 30 秒以上。

统一响应结构

字段	类型	说明
success	boolean	是否解析成功
platform	string	平台标识：shopee / amazon / xhs / douyin / instagram
data	object\|null	解析结果数据（成功时有值）
error	string\|null	错误信息（失败时有值）
elapsed_ms	number	服务端处理耗时（毫秒）

Douyin 文案提取

POST

https://xjjuhe.site/v1/extractions

提交抖音视频或作者链接，异步提取视频文案、音频转写和分析结果。任务创建后用 GET /v1/extractions/:id 查询状态，完成后用 GET /v1/extractions/:id/result 获取结果。

字段	类型	是否必填	说明
model	string	可选	固定填 douyin-copy-extract；不传时默认使用该模型
url	string	必填	抖音视频/作者链接，也支持包含链接的分享文案
mode	string	可选	single / latest / author_popular，默认 author_popular
limit	number	可选	抓取视频数量，1-20，默认 3
metadata_limit	number	可选	元数据抓取数量，1-50，默认 10
transcribe_model	string	可选	转写模型：tiny / base / small / medium / large-v3，默认 base
device	string	可选	auto / cpu / cuda，默认 cpu
workers	number	可选	并发数，1-4，默认 2
hotwords	string	可选	热词提示，最多 500 字符
keep_video	boolean	可选	是否保留视频文件，默认 false
browser_capture	boolean	可选	是否启用浏览器采集，默认 false

创建任务

bash

curl https://xjjuhe.site/v1/extractions \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "douyin-copy-extract",
    "url": "https://v.douyin.com/xxxxx/",
    "mode": "author_popular",
    "limit": 3,
    "metadata_limit": 10,
    "transcribe_model": "base"
  }'

创建响应

json

{
  "id": "cmqxxxx",
  "task_id": "task_xxxx",
  "model": "douyin-copy-extract",
  "object": "extraction.task",
  "status": "submitted",
  "progress": 0,
  "created_at": 1781600000,
  "status_url": "/v1/extractions/cmqxxxx",
  "result_url": "/v1/extractions/cmqxxxx/result"
}

查询状态

bash

curl https://xjjuhe.site/v1/extractions/cmqxxxx \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx"

获取结果

bash

curl https://xjjuhe.site/v1/extractions/cmqxxxx/result \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx"

平台模型名使用 douyin-copy-extract；上游转写模型使用 transcribe_model。不要把 transcribe_model 写到平台模型白名单里。

计费说明

按次计费：每次成功解析按模型单价扣费
解析失败（上游错误、链接无效）不扣费，自动退款
每个平台定价独立，具体价格见定价页或模型商城
上游暂不可用时返回“当前请求较多，请稍后重试”

所有解析接口支持从分享文案中自动提取链接。例如复制抖音分享文本 "这个商品太好了 https://v.douyin.com/xxx 快来看"，直接把完整文本传给 url 字段也能正确解析。

Embeddings

POST

https://xjjuhe.site/v1/embeddings

文本向量化。返回归一化的浮点向量（一般 1024-3072 维），用于语义检索 / RAG / 聚类等场景。

请求参数

字段	类型	是否必填	说明
model	string	必填	嵌入模型 name，如 text-embedding-3-small
input	string\|array	必填	单条文本或文本数组（数组每条独立向量化）
encoding_format	string	可选	float（默认）或 base64
dimensions	number	可选	降维到指定维度（仅部分模型支持）

请求示例

bash

curl https://xjjuhe.site/v1/embeddings \
  -H "Authorization: Bearer sk-jp-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": "鸭屎香 是一个 OpenAI 协议兼容的模型聚合平台"
  }'

响应示例

json

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "embedding": [-0.012, 0.034, ..., 0.078],
      "index": 0
    }
  ],
  "model": "text-embedding-3-small",
  "usage": {
    "prompt_tokens": 18,
    "total_tokens": 18
  }
}

列出可用模型

GET

https://xjjuhe.site/v1/models

返回当前账号可调用的所有模型。如果该 API Key 配置了模型白名单，只会返回白名单内的模型。响应格式与 OpenAI 完全一致。

响应示例

json

{
  "object": "list",
  "data": [
    {
      "id": "gpt-4o-mini",
      "object": "model",
      "created": 1700000000,
      "owned_by": "openai"
    },
    {
      "id": "claude-3-5-sonnet",
      "object": "model",
      "created": 1700000000,
      "owned_by": "anthropic"
    },
    {
      "id": "gemini-2.5-pro",
      "object": "model",
      "created": 1700000000,
      "owned_by": "google"
    }
  ]
}

Codex 专用模型列表

GET

https://xjjuhe.site/v1/codex/models

Cockpit Tools 等客户端需要精简模型列表时，将基础地址设为 https://xjjuhe.site/v1/codex，保留原 API Key 后重新获取模型。原 /v1/models 继续返回全类型模型，不受此展示开关影响。

bash

curl "https://xjjuhe.site/v1/codex/models" -H "Authorization: Bearer $API_KEY"

专用列表只返回管理员已加入、已上架的对话模型，再按 Key 模型白名单与 IP 白名单校验。默认不自动加入模型；无符合项返回 200 和空数组。后台入口为“模型管理”，owner 可单个编辑或勾选后批量加入、移出。

json

{
  "object": "list",
  "data": [{
    "id": "EXAMPLE_CHAT_MODEL",
    "object": "model",
    "created": 1700000000,
    "owned_by": "example",
    "category": "chat",
    "context_length": 128000,
    "supports_stream": true,
    "supports_tools": true,
    "supports_vision": false
  }]
}

详情使用 GET /v1/codex/models/模型名。无效 Key 返回 401，失效、余额/额度不足或 IP 不允许返回 403，未展示或无模型权限的详情返回 404。列表与详情均禁止缓存，不返回管理成本和渠道凭证。

POST

https://xjjuhe.site/v1/codex/responses

POST

https://xjjuhe.site/v1/codex/chat/completions

两个 POST 地址直接复用原接口的鉴权、路由、计费和流式处理，不新增图片、视频或 Messages 前缀接口。展示开关不是调用权限：移出列表不会禁止手填模型名调用。加入列表也不代表上游已通过 Codex、Responses、工具调用或流式验收，需以实际模型和渠道能力为准。

用 OpenAI 协议调用 Claude / Gemini / 国产模型

平台已自动完成跨厂商协议转换 —— 你只需把 model 改成对应模型名，其余请求结构完全不变。

厂商	model 字段示例
OpenAI	gpt-5, gpt-4o, gpt-4o-mini, o3
Anthropic	claude-opus-4-1, claude-sonnet-4, claude-3-5-sonnet
Google	gemini-2.5-pro, gemini-2.5-flash, gemini-2.0-flash
DeepSeek	deepseek-r1, deepseek-v3, deepseek-chat
阿里通义	qwen3-max, qwen3-coder
Moonshot Kimi	kimi-k2
智谱 GLM	glm-4.6
豆包	doubao-1.5-pro
xAI	grok-4
图像	gpt-image-2
视频	veo_3_1-fast-remix, veo_3_1-hd-remix
商品解析	shopee-extract, amazon-product, xhs-crawl, douyin-product, wechat-channels-parse, ins-parse

完整的最新模型清单可通过 GET /v1/models 接口拉取，或在模型市场页面查看含价格的完整列表。