映序 API 接口文档
更新:2026-11-15 · 版本: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":"API_ENDPOINT_DISABLED","message":"此接口未对外开放。"}}
常用状态码:400 参数有误;401 密钥缺失、无效或撤销;402 余额不足;403 权限或来源校验失败;404 记录不存在或接口未开放;409 版本、状态或幂等冲突;429 请求频繁;503 服务暂未就绪。
2. 视频生成
以下路径相对于 API 基础地址。
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /models |
查询视频模型及当前账号售价 |
| POST | /tasks |
创建视频任务 |
| GET | /tasks/{taskId} |
查询任务进度、结果与结算状态 |
| GET / HEAD | /tasks/{taskId}/asset |
读取已完成并结算的成片或生成图片 |
| GET / HEAD | /uploads/{uploadId} |
读取当前账号的素材图片 |
先从 /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. 文字剧本工作台仅供网站使用
文字剧本工作台仅供网站内使用。资产提取、分镜文案、视频描述词生成、编辑、恢复、重试和重做,请登录网站操作。相关文字工作台 API 返回 404,错误码为 API_ENDPOINT_DISABLED。工作台资产生图仍是独立开放的 API 模块。
4. 资产生图
资产生图操作使用网站内已有的工作台任务编号 jobId 和资产编号 assetIds。文字工作台列表、详情、创建和编辑 API 已关闭;需要任务版本 revision 的图片设置操作,请使用网站当前版本。图片生成返回的 taskIds 可通过通用任务查询与下载接口取得结果。
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. 项目与素材衔接
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /studio/connection |
检查密钥连接,返回账号及脱敏邮箱 |
| GET | /studio/projects |
列出项目;支持 limit、cursor |
| GET | /studio/projects/{projectId} |
项目、资产和分页分镜 |
| GET | /studio/assets?projectId=PROJECT_ID |
项目资产;支持 limit、cursor |
| POST | /studio/projects |
创建项目,常用 name、source、externalId |
| POST | /studio/uploads |
上传图片,正文 { "dataUrl": "data:image/png;base64,..." },完整 JSON 上限 8 MiB |
| POST | /studio/assets |
创建资产:projectId、kind、name、description、uploadId、source、externalId;kind 为 character/scene/prop |
| POST | /studio/assets/{assetId}/save |
编辑资产:revision,及 name/kind/description/uploadId 中需修改的字段 |
| POST | /studio/projects/{projectId}/shots/import |
导入分镜:source、shots;每次 1~100 条 |
分镜导入每项可含 externalId、label、prompt、assetIds、excludedAssetIds、settings。按 source + externalId 去重。
使用个人项目素材制作视频:读取项目分镜 prompt 和对应资产 uploadId,按需填写视频 /tasks 的 imageUploadIds,使用实时模型参数与预算提交。任务之间的归属、版本和引用由服务端校验。