# 映序 API 接口文档 更新:2026-11-15 · 版本:v1 服务地址:`https://yingxu.top` API 基础地址:`https://yingxu.top/api/plugin/v1` 支持视频生成、工作台资产生图、参考素材上传读取、个人项目与资产管理。剧本提取、分镜文案、视频描述词生成仅供网站内使用。所有任务使用密钥所属账号的余额、权限与实际售价。 ## 1. 访问密钥与通用约定 登录映序,在「密钥与接入」创建客户访问密钥。请求头: ```http 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 请退避重试。 错误格式: ```json {"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 和规格请替换成目录中的可用值: ```bash 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`。 ```bash 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`、`review`。`review` 表示受理、费用或结果待核对,应继续查询原任务。下载前确认 `completed` 且已结算。查询及下载均校验密钥所属账号。 ## 3. 文字剧本工作台仅供网站使用 文字剧本工作台仅供网站内使用。资产提取、分镜文案、视频描述词生成、编辑、恢复、重试和重做,请登录网站操作。相关文字工作台 API 返回 404,错误码为 API_ENDPOINT_DISABLED。工作台资产生图仍是独立开放的 API 模块。 ## 4. 资产生图 资产生图操作使用网站内已有的工作台任务编号 jobId 和资产编号 assetIds。文字工作台列表、详情、创建和编辑 API 已关闭;需要任务版本 revision 的图片设置操作,请使用网站当前版本。图片生成返回的 taskIds 可通过通用任务查询与下载接口取得结果。 ### 4.1 模型和设置 ```http GET /studio/workbench/image-models ``` 返回 `models` 数组,每项有 `id`、`name`、`status`、`resolutions`、`ratios`、`prices`、`revision` 等公开字段。`prices` 按规格列出当前账号价格,单位为分。 设置示例: ```json {"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 先报价,再生成 ```http POST /studio/workbench/{jobId}/image-quote ``` ```json {"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: ```http POST /studio/workbench/{jobId}/images ``` ```json {"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}`。图片成功后通常自动绑定到资产;若资产期间被编辑而未绑定,确认最新版本后调用: ```http POST /studio/workbench/{jobId}/apply-image ``` ```json {"taskId":"IMAGE_TASK_ID","assetRevision":3} ``` 有多套着装的同一人物,可调用 `POST /studio/workbench/{jobId}/primary-character`,正文 `{ "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`,使用实时模型参数与预算提交。任务之间的归属、版本和引用由服务端校验。