映序 API 接口文档

更新：2026-10-27 · 版本：v1

服务地址：https://yingxu.top

API 基础地址：https://yingxu.top/api/plugin/v1

支持视频生成，以及剧本工作台的资产提取、分镜文案、视频描述词、资产生图、编辑和结果导入。所有任务使用密钥所属账号的余额、权限与实际售价。

1. 访问密钥与通用约定

登录映序，在「密钥与接入」创建客户访问密钥。请求头：

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

GET 无需 Content-Type。服务端调用不携带 Cookie，也不需要 CSRF Token。密钥只放在自己的服务端；撤销后立即停止访问。浏览器跨站请求不属于开放 CORS 范围。

金额单位为人民币「分」，100 分＝¥1；不要把站内积分直接填入金额字段。使用接口返回的账号报价，提交金额、归属、状态等均由服务端核算。

创建视频任务使用 Idempotency-Key 请求头；剧本任务和资产生图使用正文中的 requestKey。一次业务请求固定使用同一编号，重试时保持正文一致；内容变化必须使用新编号。同编号但正文不同返回 409。

工作台采用异步处理，建议每 3～5 秒查询一次。当前每个密钥上限 600 次/分钟；工作台读取按账号 360 次/分钟、写入 240 次/分钟，付费处理入口另有 30 次/分钟限制，报价入口 60 次/分钟。视频提交按账号 30 次/分钟。遇到 429 请退避重试。

错误格式：

{"error":{"code":"WORKBENCH_CONFLICT","message":"记录已更新，请刷新后重试。"}}

常用状态码：400 参数有误；401 密钥缺失、无效或撤销；402 余额不足；403 权限或来源校验失败；404 记录不存在或接口未开放；409 版本、状态或幂等冲突；429 请求频繁；503 服务暂未就绪。

2. 视频生成

以下路径相对于 API 基础地址。

先从 /models 返回的 models 数组选择模型，读取其 id、durations、resolutions、aspectRatios（若该模型返回 ratios，以实际字段为准）、limits 和 pricing。模型目录及售价会更新，使用实时返回值，不固定写死。

视频提交示例，模型 ID 和规格请替换成目录中的可用值：

curl 'https://yingxu.top/api/plugin/v1/tasks' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: VIDEO_REQUEST_UUID' \
  --data '{"modelId":"yingxu-video-009","prompt":"人物在窗边缓缓转身，神情由惊讶转为坚定。","duration":15,"resolution":"720p","aspectRatio":"16:9","maxCostCents":460}'

新建返回 201，重复请求返回 200，正文包含 task。maxCostCents 是本次允许的最高金额；若实际报价超过预算，提交会被拒绝。示例预算仅用于演示，专属价格以账号实时结果为准。

参考图片使用 imageUploadIds 或 imageUrls 数组。音频、视频参考分别为 audioUploadIds / audioUrls、videoUploadIds / videoUrls，仅在所选模型支持时使用。URL 须为公开可访问的 HTTPS 文件；数量、类型、时长、大小均以模型规格为准。已有工作台资产图片可直接使用其 uploadId。

curl 'https://yingxu.top/api/plugin/v1/tasks/TASK_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY'

curl 'https://yingxu.top/api/plugin/v1/tasks/TASK_ID/asset' \
  -H 'Authorization: Bearer YOUR_API_KEY' -o result.mp4

常见视频状态：queued、running、processing、completed、failed、cancelled。提交失败或明确生成失败会自动退款；已受理的任务持续查询，成片同步异常会自动重试。下载前确认 completed 且已结算。查询及下载均校验密钥所属账号。

3. 剧本工作台：推荐流程

工作台前缀：/studio/workbench。

1. POST 创建剧本，target: "assets"，先提取人物、场景、物品。
2. GET 轮询任务，直到 status: "assets_ready"；读取 state.assets 和 projectAssets。
3. 按需要编辑资产描述、生成资产图片。
4. POST /{jobId}/storyboard，选择 15 秒或 30 秒分镜。
5. GET 轮询到 completed；读取 state.frames[].text 和 state.frames[].videoPrompt。
6. POST /{jobId}/import，同步到本站项目和批量视频；也可直接取描述词调用视频 /tasks。

若无需在资产阶段停下来检查，创建时使用 target: "complete"，连续执行资产、分镜与视频描述词。该选项生成文字结果，视频文件仍需单独提交视频任务。

3.1 查询列表与文字价格

GET /studio/workbench?page=1

返回 jobs、total、page、pages、configured、prices。每页 30 条。当前文字价格如下，实际以接口及任务 billing.prices 快照为准：

费用按步骤冻结，完成后结算；未完成或取消的部分退回。同一已交付步骤不会因普通恢复重试而重复收费。资产生图、视频生成另行计费。

3.2 创建剧本任务

curl 'https://yingxu.top/api/plugin/v1/studio/workbench' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"requestKey":"SCRIPT_REQUEST_UUID","jobs":[{"name":"雨夜归来","script":"室内，夜。张岚推门进入。\n张岚：这笔钱，我一分也不会拿。","template":"classic","style":"真人短剧，RAW 照片级真实感","target":"assets"}]}'

整个工作台请求 JSON 上限 2 MiB，大批量剧本请分次提交。提交返回 202：

{"jobs":[{"id":"JOB_ID","name":"雨夜归来","status":"queued","target":"assets","revision":0}]}

以上为响应字段节选；实际还包含计费、时间、进度等字段。

3.3 查询结果

GET /studio/workbench/{jobId}

返回 { "job": {...} }。主要字段：

personality 为人物声线/表演资料；同一人物不同服装可分别作为独立人物资产，保留返回的完整名称。

工作台时间字段是 Unix 毫秒。状态包括 queued、running、assets_ready、completed、failed、paused、cancelled。assets_ready 等待调用方确认；failed 应先查看错误和已保存内容，再恢复或重试。

响应只交付创作结果与操作所需信息，不返回访问凭据、上游地址或内部处理记录。

3.4 开始分镜与视频描述词

POST /studio/workbench/{jobId}/storyboard

{"revision":12,"duration":15}

仅 assets_ready 可开始；duration 为 15 或 30。revision 使用最新 GET 的值。该操作会继续生成分镜文案和视频描述词。返回 200，job.status 进入队列。

3.5 编辑、恢复和导入

以下均为 POST，路径相对于 /studio/workbench/{jobId}；无参数也发送 {}。

大多数操作返回 {job: ...}；rebuild-script 新建时返回 202；import、delete 返回各自结果。WORKBENCH_CONFLICT 表示版本已更新，应重新 GET 并核对修改内容。普通恢复和 retry 保留已有交付结果；regenerate-video 是新的付费交付。

4. 资产生图

4.1 模型和设置

GET /studio/workbench/image-models

返回 models 数组，每项有 id、name、status、resolutions、ratios、prices、revision 等公开字段。prices 按规格列出当前账号价格，单位为分。

设置示例：

{"modelId":"yingxu-image-实际模型ID","resolution":"1K","characterLayout":"three-view","sceneLayout":"single","propLayout":"white-background","showName":true}

modelId 必须使用目录返回值。resolution 使用模型支持的 1K、2K、4K、1080p 或 native。人物布局支持 three-view、four-view、concept；场景支持 single、four-view、board、concept；物品使用 white-background。比例按布局生成：人物四视图 3:4，其他布局 16:9；模型需支持对应比例。

可通过 POST /studio/workbench/{jobId}/image-settings 保存 { "revision": 12, "settings": {...} }。

4.2 先报价，再生成

POST /studio/workbench/{jobId}/image-quote

{"assetIds":["ASSET_ID"],"interactionVersion":2,"settings":{"modelId":"IMAGE_MODEL_ID","resolution":"1K","characterLayout":"three-view","sceneLayout":"single","propLayout":"white-background","showName":true}}

assetIds 使用任务 projectAssets[].id，1～900 项，不能重复。返回 quoteHash、totalCents、currency、settings、modelName、items。每项含资产 ID、实际生图提示词、比例和价格。

随后用相同 assetIds、settings、interactionVersion，并增加 quoteHash、UUID 格式的 requestKey：

POST /studio/workbench/{jobId}/images

{"assetIds":["ASSET_ID"],"interactionVersion":2,"settings":{"modelId":"IMAGE_MODEL_ID","resolution":"1K","characterLayout":"three-view","sceneLayout":"single","propLayout":"white-background","showName":true},"quoteHash":"QUOTE_HASH","requestKey":"IMAGE_REQUEST_UUID"}

返回 202，含 taskIds、totalCents（首次提交）、repeated。轮询工作台详情的 imageJobs，或 /tasks/{taskId}。图片成功后通常自动绑定到资产；若资产期间被编辑而未绑定，确认最新版本后调用：

POST /studio/workbench/{jobId}/apply-image

{"taskId":"IMAGE_TASK_ID","assetRevision":3}

同一人物的多套着装可调用 POST /studio/workbench/{jobId}/primary-character；同一地点的多个时段场景可调用 POST /studio/workbench/{jobId}/primary-scene。正文为 { "assetId": "主参考资产ID", "revision": 12 }。其他人物造型或同组场景会引用主参考；可先生成主参考，也可同批提交。

图片下载使用返回的 imageUrl，加本站域名并携带 Bearer 密钥；路径通常为 /api/plugin/v1/uploads/{uploadId}。不要将密钥放进 URL。

5. 项目与素材衔接

分镜导入每项可含 externalId、label、prompt、assetIds、excludedAssetIds、settings。按 source + externalId 去重。工作台的 /import 已完成关联时，直接读取返回 projectId 即可。

从工作台制作视频：读取项目分镜 prompt 和对应资产 uploadId，按需填写视频 /tasks 的 imageUploadIds，使用实时模型参数与预算提交。任务之间的归属、版本和引用由服务端校验。

6. Python 接入示例

安装依赖：pip install requests。设置环境变量 YINGXU_API_KEY 后执行。以下示例会创建一个收费的资产提取任务：

import os, time, uuid, requests

base = "https://yingxu.top/api/plugin/v1"
session = requests.Session()
session.headers.update({"Authorization": "Bearer " + os.environ["YINGXU_API_KEY"]})

def call(method, path, body=None):
    response = session.request(method, base + path, json=body, timeout=60)
    response.raise_for_status()
    return response.json()

payload = {
    "requestKey": str(uuid.uuid4()),  # 网络重试时复用同一个 payload
    "jobs": [{
        "name": "雨夜归来", "script": "室内，夜。张岚：这笔钱，我一分也不会拿。",
        "template": "classic", "style": "真人短剧，RAW 照片级真实感", "target": "assets"
    }]
}
job_id = call("POST", "/studio/workbench", payload)["jobs"][0]["id"]
deadline = time.monotonic() + 1800
while time.monotonic() < deadline:
    job = call("GET", f"/studio/workbench/{job_id}")["job"]
    if job["status"] == "assets_ready":
        print(job["state"]["assets"])
        break
    if job["status"] in {"failed", "paused", "cancelled"}:
        raise RuntimeError(f"{job.get('errorCode')}: {job.get('note')}")
    time.sleep(5)
else:
    raise TimeoutError(f"轮询超时，请继续查询原任务 {job_id}，勿新建重复任务")

# 确认资产后再执行以下收费步骤：
# call("POST", f"/studio/workbench/{job_id}/storyboard",
#      {"revision": job["revision"], "duration": 15})

联网超时不等于业务失败。创建请求超时后使用原 requestKey 和原正文重试；已拿到 jobId/taskId 的任务继续查询原编号。遇到余额不足，已完成内容会保留，充值后使用原任务恢复入口。