接口文档

兼容 OpenAI 协议的视频生成接口。拿一把 API 密钥，就能用你熟悉的 SDK 直接调。

一、准备：拿密钥

1. 登录 控制台。账号由我们开通；充值请加微信 XYSM2015。
2. 左侧 API 密钥 → 添加密钥 → 复制 sk- 开头那串。
3. 按下面的例子调用即可。

二、Base URL 与接口地址

所有接口都在这个地址下（带 /v1，用 OpenAI SDK 时填这个作 base_url）：

Base URL： https://xyjingyuapi.com/v1

POST /videos                  提交一个视频任务
GET  /videos/{id}             查进度（完成后这里会给 artifact.url）
GET  /videos/{id}/content     取成片（返回 mp4 字节流；要带 Authorization，路径没有扩展名）
GET  /models                  当前可用的型号列表

OpenAI SDK 里就这样填：

from openai import OpenAI
client = OpenAI(base_url="https://xyjingyuapi.com/v1", api_key="sk-你的密钥")

三、快速开始

三步：提交 → 查进度 → 取片。下面每步给一个能直接跑的最小例子， 完整可跑的 Python（含断点续传与完整性校验）在 附录 A。

1. 提交任务

curl https://xyjingyuapi.com/v1/videos \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nh-2.5-t-720p",
    "prompt": "镜头缓慢推近，人物微微转头看向镜头，光影自然流动",
    "size": "720x1280",
    "images": ["https://你的图床/人物.jpg"]
  }'

四个必填，缺一个就 400、不提交、不扣费：

为什么 size 必须给：不传就由通道自己决定方向 —— 要竖屏却拿到横屏，而且全程没有提示。size 和 aspect_ratio 都传时 以 aspect_ratio 为准（见第六节）。 参考图怎么填、多张为什么都生效、URL 有什么要求 —— 见第四节。

成功返回任务 id，存下来 —— 查询和取片都靠它。丢了只能重新生成（＝再扣一次费）：

{
  "id": "Lmvovrjyscomr9",        // ★ 后面的查询、取片都用这个 id
  "object": "video",
  "created_at": 1769900000,
  "status": "queued",
  "model": "nh-2.5-t-720p",
  "progress": 0,
  "seconds": "15"
}

2. 查进度

curl https://xyjingyuapi.com/v1/videos/任务id \
  -H "Authorization: Bearer sk-你的密钥"

status 只有四种值，别自己加判断：

• progress 是粗档，不是真实百分比：只有 0 / 50 / 100 三档 （上游只回状态、不回进度）。别拿它做进度条门槛，也别拿它判断"是不是卡住了"。
• 轮询 15~30 秒一次：15 秒的片子实测 5~20 分钟，30 秒的 10~40 分钟。 别一秒一次 —— 我们按次限流，你只会拿到一堆 429。
• 超时上限 200 分钟：到点还没终态，我们这边已经退款，你去查一次就会看到 failed。
• failed 时多一个 error，code 只有两种： generation_failed（素材或参数不合要求）、 video_cancelled（任务被取消并退款）。

3. 取成片：只有一条路

curl https://xyjingyuapi.com/v1/videos/任务id/content \
  -H "Authorization: Bearer sk-你的密钥" \
  -o 我的片子.mp4

返回的是 mp4 字节流本身（不是 JSON、也不是跳转）。地址就是进度响应里的 artifact.url —— 它是相对路径，拼上 Base URL 就能用。照它用，不要自己拼。

• 成片是 H.264（avc1） 的 mp4，浏览器、剪辑软件都能直接打开。
• 支持 Range 断点续传（响应头有 accept-ranges: bytes）：没下完就带 Range: bytes=<已下的字节数>- 接着下，不用从头再来。片子 4~10MB，慢网下这点很重要。
• 保留 24 小时（从生成完成算）：24 小时内重复下载不再扣费；超过返回 410 gone。 ⇒ 出片即取，转存到你自己的存储，别把它当永久地址。

四、参考图：所有视频型号都必须带（最多 9 张）

至少 1 张，最多 9 张，值是公网能访问的 http(s) 图片地址。两种字段各管一件事：

顺序有意义：模型按你给的顺序取参考，越靠前权重越高。首帧（这一镜从哪开始） 建议放第一个。用 images 时第一个元素就是首帧。

顺便说一句参考音频：如果你要带音频参考，只支持 WAV / MP3，且每条不超过 5 秒。 音频是辅助项，出问题我们会在提交时自动去掉重试一次，不会连累整条片子。

三种写法都认：

// ① 多张（推荐）。images 是数组，最多 9 张，全部生效
"images": [
  "https://你的图床/首帧.jpg",
  "https://你的图床/人物B.jpg",
  "https://你的图床/场景.jpg"
]

// ② 只带首帧（OpenAI Sora 标准写法）
"input_reference": "https://你的图床/首帧.jpg"

// ③ 兼容老写法 / 第三方 SDK
"image": "https://…/a.jpg"

// ①+② 一起给也没问题：两张都算，同一张重复给会自动去重

越接近你想要的画面（构图、人物、光线）出片越准。参考图必须是图片，不要传视频链接。

4.1 上传本地图片（本地文件 → 公网 URL）

如果你手里是本地文件（软件截图、手机照片），先调一次上传，拿到 URL 再提交视频。

POST https://xyjingyuapi.com/v1/uploads
Authorization: Bearer sk-你的Key
Content-Type: application/json

{
  "filename": "ref.png",
  "content_type": "image/png",
  "data": "<图片字节的 base64>"
}

→ 200 {"object":"file","url":"https://…/ref.png","size":123456}

• 只收图片（PNG / JPG / WEBP，按文件内容的真实类型判，不看文件名）。其它类型 415。
• 单个文件上限 16MB（提交前我们会自动压到长边 1920，压完一般 100~250KB，不影响出片）。超了回 413 —— 我们不收下再被上游拒，那样你会白等一趟。
• data 可以带 data:image/png;base64, 前缀，我们会自动剥掉。
• 会把文件头（魔数）验一遍：内容其实不是图片就回 415（防止把文本/半截文件当图片传上去，最后出片才失败）。
• 上传不收费，也不消耗额度；但 Key 必须有效（已吊销的 Key 用不了）。
• 拿到的 url 放进 images 数组（或 input_reference）即可； 同一张图重复上传只占一份（按内容哈希存）。
• 不接受音频：这个接口的视频不收参考音频，传上去也不会被使用。

五、seconds 怎么填：看型号

每个型号的时长是型号本身定好的，不需要你选。但要不要传 seconds， 取决于这个型号怎么计费 —— 下表「seconds」一列写得很清楚，照它来就行。

• 固定时长 + 按条计费（大多数）：不用传。传了也必须等于它的固定秒数 （比如固定 15 秒就传 "15"），传别的值会 400 fixed_duration。
• 按秒计费：必须传，不传会 400 并告诉你该传多少。范围见下表。

六、画面比例 ≠ 分辨率档位

这两个经常被混在一起问，其实是两件事：

七、型号与价格

型号名请原样复制（区分大小写，也含中文和括号）。表里的名字与软件里、 后台里、教程里显示的是同一个 —— 换行、少一个括号都会对不上。

控制台余额直接以元显示（充 10 元就是 10 元）。上表的「点」是软件里同一套计价单位， 10 点 = 1 元。每次调用按上表扣一次；失败会自动退回，不用找我们。

这张表跟着线上在售数据自动更新（每 15 分钟一次）。也可以随时拉接口，拿到的就是当前在售清单：

curl https://xyjingyuapi.com/v1/models \
  -H "Authorization: Bearer sk-你的密钥"

图片型号（出图，同步返回）

出图走 POST /v1/images/generations，同步返回 （response_format 默认给 URL，也可以要 b64_json）。 必须传 size（像素或比例都行），不传会被拒 —— 我们不替你猜画幅。

图片按张计费：n 只能是 1，要几张就调几次。 失败自动退回，和视频一个口径。

文本型号（对话 / 写作，按 token 计费）

走标准 OpenAI 对话接口 POST /v1/chat/completions，同步返回， 你原来调 OpenAI 的代码改个 base_url 就能用。

输出比输入贵（各家都这样），因为生成的每个字都要算一遍。 上面是"每百万 token"的单价 —— 一篇文章通常几千 token，实际扣的是分位。

curl https://xyjingyuapi.com/v1/chat/completions \\
  -H "Authorization: Bearer sk-你的密钥" \\
  -H "Content-Type: application/json" \\
  -d '{"model":"tt-5.2",
       "messages":[{"role":"user","content":"把这句话改得更口语：此事尚需进一步商讨。"}]}'

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "choices": [ { "message": { "role": "assistant", "content": "这事儿还得再商量商量。" } } ],
  "usage": { "prompt_tokens": 28, "completion_tokens": 12, "total_tokens": 40 }
}

八、每个型号能吃多少素材

准备素材前先看这张表：参考图 / 参考视频 / 参考音频各能吃几段、 描述词最多写多少字、出片分辨率。数字取自我们服务端的真实上限 （不是模型厂商文档里那个更宽松的数字）—— 超了会被拒绝或裁掉，按这张表准备最省事。

九、常见报错

报错都是这个形状，message 直接写清怎么改：

{
  "code": "input_reference_required",
  "message": "This model requires at least one reference image. Pass it as "input_reference": "https://…/image.jpg" (public http(s) URL)."
}

十、账单与答疑

• 控制台 → 使用日志：每次调用都有记录（哪个型号、扣多少、成功还是失败）。
• 余额在钱包页查看，充值请加微信 XYSM2015。
• 失败的调用自动全额退回，不需要申请；failed 之后再查一次就能看到余额回来。

用了上面还搞不定，把三样发我，能马上定位：

1. 任务 id
2. 型号名
3. 报错原文

微信：XYSM2015（加时说一句"API"，通过得快些）

十一、出图（图片生成）

协议与 OpenAI 的图片接口一致，同步返回（等出图完成才回包，通常 5~60 秒）：

curl https://xyjingyuapi.com/v1/images/generations \
  -H "Authorization: Bearer sk-你的本站密钥" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2","prompt":"雨夜的旧书店，暖黄灯光，电影感","size":"1024x1024"}'

本站返回的是外链（不是 base64）：

{
  "created": 1793175091,
  "data": [ { "url": "https://…/20261028161158_18e2a34522c0e7e24bac.png" } ]
}

主站那条链路返回 base64（data[0].b64_json），例子见本节末尾的老示例——按你要接哪边选。

curl https://jingyumanju.com/v1/images/generations   -H "Authorization: Bearer ak_你的密钥"   -H "Content-Type: application/json"   -d '{"model":"tt-image-2","prompt":"雨夜的旧书店，暖黄灯光，电影感","size":"16:9"}'

{
  "created": 1769900000,
  "data": [ { "b64_json": "iVBORw0KGgoAAAANSUhEUg..." } ],
  "id": "Lmvovrjyscomr9"
}

三个参数要点（两边都适用）：

• size 必填。写比例（16:9 / 9:16 / 1:1）或像素 （1920x1088）都行。不传会 400，我们不会偷偷给你一张默认画幅的图。
• n 只收 1（一次一张，一次一扣）。要多张就多调几次。
• image / images：参考图（图生图），两条路都行：
  ① 给公网 http(s) 地址（本地文件先用 POST /v1/uploads 换地址）；
  ② 直接上传文件（multipart，字段名 image）。
  我们就把这张图真的交给模型按它改，而不是无视它另画一张。 一次只收 1 张 —— 多张会明确回 400（不会只取第一张了事）。

可用型号与价格随时变，以 GET /v1/models 为准 （看 supported_endpoint_types 里带 image-generation 的那几条）。 这几个图片型号都支持图生图。

10.1 出图会遇到的报错

十二、不想写代码？用「字字动画」插件

如果你只是想在剪辑/动画软件里生成画面，不用自己调接口 —— 我们把它做成了 字字动画的两个插件（视频 + 出图），装上就能在字字里选型号、填描述、直接出片。

查看插件说明 / 下载插件包 →

• 压缩包里是两个插件文件夹（video_plugin_jingyu + image_plugin_jingyu） 和一份说明书。把这两个文件夹分别复制到字字动画安装目录下的 _internal\plugins\video_plugins\ 与 _internal\plugins\image_plugins\， 然后重启字字动画。（没有安装程序 —— 不用双击任何 exe，就是复制这两个文件夹。）
• 当前版本 0.17（视频插件、出图插件同版本）。装过 0.16 的请换一次： 修「出图插件型号名写错」—— 0.16 那一版填的是主站型号名（tt-image-*）， 而这个插件连的是本站，站里没有这些型号，选了会提交失败；现在换成本站真实的 gpt-image-2 / gpt-image-2.5 / banana-2.1 （没填 Key 时下拉的兜底表也对得上了）。 同时把一件事说清：出图是「文生图」，暂不支持参考图 —— 分镜带了参考图时日志会明确说"已忽略 N 张"，不会假装用上了； 要按图锁人物/场景请用视频型号（那些都收参考图）。
  此前 0.15： 修「选完型号没保存」（假选中）：认不出线上型号时不再把配置改成第一个；下拉始终显示你选的那个。
  此前 0.14：报错说人话（英文 JSON 转成中文并给改法），并修掉「空的参考视频字段被上游判为不支持的字段」。
  此前 0.13 的说明：：提交前用客户自己的 Key 核对在售清单，不在清单里就拦下（不提交、不扣费）并给出改法；「提交型号」会写进运行日志便于查证。下拉也补上了型号名（线上清单原本没有显示名，只有内部代号）。0.12 的上传前压图仍在内。
  此前 0.12 的说明：真机实测 4.2MB 的图 41.9 秒 → 2.3 秒（省 95%）。真因是体积（参考图常是 1.5~4MB 的 PNG，而上传只收 base64，再涨 1/3）。现在上传前本地压到长边 1280 / JPEG q85；透明图与动图不碰（转 JPEG 会压成黑底）、压不小就发原图、压缩组件不可用时自动退回原图。另外 0.11 修了「大图并行把上行挤断」（按体积自适应）、0.10 修了「选什么型号都生成同一个型号」。0.10 那三件事 —— ① 「选什么型号都生成同一个型号」：面板拉完线上清单会重建下拉，而重建只改了界面显示、 没把选择写回配置 ⇒ 界面显示你选的、提交用的是旧型号。现在重建后会回写，看到什么就发什么。 ② 参考图上传：以前一张一张排队传且完全不重试，6~9 张图既慢、又会被一次连接抖动整批打断 （报 Connection aborted / SSLError EOF）。现在 3 张并行、连接类错误重试 2 次、 同一张图传过一次不再重复传；顺序仍按入参，@图片1 编号不会乱。 ③ 上传彻底失败时给中文人话，不再甩异常栈。 你的 Key 和设置不受影响，装上 0.10 会自动读回来。
• 插件里的型号是联网拉线上清单的 —— 我们上下架型号不用你重装插件。
• 插件只连本站（xyjingyuapi.com），用 sk- 开头的密钥。 主站（jingyumanju.com + ak_ 密钥）是软件自己用的那条链路， 两条互不影响，密钥也不通用。
• 视频插件能用的型号＝面板里拉到的那份线上清单（型号名后面带「秒数 · 价格」）。这里不再写死数量：上下架随时会变，写死的数字一定会过期。清单里没有某个型号只有两种可能：它下架了，或那条供货通道被临时停用了。
• 地址永久不变，换版本也不用重新找链接： https://xyjingyuapi.com/download/plugin-pack

附录 A：完整 Python 示例（提交 → 轮询 → 取片）

照抄就能跑。注意最后一步用的是响应里给的 artifact.url， 并且落盘后要验完整性（字节数 / ftyp / moov）—— 只判断"写了多少字节"会把半截片子当成功，播放器却打不开。

import os, time, requests

BASE = "https://xyjingyuapi.com"          # 不含 /v1
API = BASE + "/v1"
H = {"Authorization": "Bearer sk-你的密钥"}

r = requests.post(API + "/videos", headers=H, json={
    "model": "nh-2.5-t-720p",
    "prompt": "镜头缓慢推近，人物微微转头看向镜头",
    "size": "720x1280",          # ★ 必填：竖屏 9:16。不传会 400（size_required）
    "aspect_ratio": "9:16",      # ★ 建议：显式给比例，服务端优先用它（和 size 说的是同一件事）
    "images": ["https://你的图床/ref.jpg"],   # ★ 必带；首帧用 input_reference
})
r.raise_for_status()
vid = r.json()["id"]

while True:
    s = requests.get(API + "/videos/" + vid, headers=H).json()
    print(s["status"], s.get("progress"))
    if s["status"] in ("completed", "failed"):
        break
    time.sleep(15)               # 15~30 秒一次就够，别更密

if s["status"] != "completed":
    print("失败原因：", s["error"]["message"], "（钱已退回）")
    raise SystemExit(1)

# ★ 用响应里给的地址（相对路径），不要自己拼、也不要去找任何"直链"
url = BASE + s["artifact"]["url"]
path = "片子.mp4"
for _try in range(3):
    have = os.path.getsize(path) if os.path.exists(path) else 0
    hdrs = dict(H)
    if have:
        hdrs["Range"] = "bytes=%d-" % have            # 断点续传
    with requests.get(url, headers=hdrs, stream=True, timeout=180) as resp:
        if resp.status_code == 416:                   # 已经下全了
            break
        resp.raise_for_status()
        # 200 = 整份重给 ⇒ 必须从头覆盖；206 = 续传 ⇒ 接着写
        append = (resp.status_code == 206 and have > 0)
        total = resp.headers.get("Content-Length")
        with open(path, "ab" if append else "wb") as f:
            for chunk in resp.iter_content(256 * 1024):
                if chunk:
                    f.write(chunk)
    size = os.path.getsize(path)
    ok_size = (not total) or size == (have if append else 0) + int(total)
    blob = open(path, "rb").read()
    if ok_size and b"ftyp" in blob[:32] and b"moov" in blob:
        break                                          # 三条都过才算下好
    print("这次没下完（%d 字节），接着下…" % size)
else:
    raise RuntimeError("下载不完整 —— 别重新生成（会再扣一次），到控制台「日志」里手动下载")

print("已保存，字节数 =", os.path.getsize(path))

需要"下成片"这个单独函数的话，把上面 for _try in range(3): 那一段抽出来就是 —— 不要另写一份，两份必然漂移。