# 映序 API 接口文档

更新：2026-10-27 · 版本：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":"WORKBENCH_CONFLICT","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. 剧本工作台：推荐流程

工作台前缀：`/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 查询列表与文字价格

```http
GET /studio/workbench?page=1
```

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

| prices 字段 | 项目 | 单价 |
|---|---|---|
| assets | 每个剧本的资产提取 | 120 分 |
| storyboard | 每条分镜文案 | 5 分 |
| video | 每条视频描述词 | 5 分 |
| regenerate | 单条视频描述词重新生成 | 20 分 |

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

### 3.2 创建剧本任务

```bash
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"}]}'
```

| 字段 | 说明 |
|---|---|
| requestKey | 必填，1～80 字符；推荐 UUID |
| jobs | 必填，至少一个剧本对象 |
| jobs[].name | 必填，1～120 字符 |
| jobs[].script | 必填，1～100000 字符；建议明确人物、台词与动作 |
| jobs[].template | 必填；`classic` 对应 15 秒，`modern` 对应 30 秒 |
| jobs[].style | 可选，默认「真人短剧」，最多 800 字符 |
| jobs[].target | 可选；`assets` 或 `complete`，默认 `assets` |

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

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

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

### 3.3 查询结果

```http
GET /studio/workbench/{jobId}
```

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

| 字段 | 说明 |
|---|---|
| id / name / script / style / template | 任务编号、剧本与配置 |
| status / phase / note / errorCode | 状态、处理阶段、说明、错误码 |
| revision | 最新记录版本，编辑和部分操作须回传 |
| billing | `prices`、`currency`、`settledCents`、`frozenCents`、`releasedCents` |
| state.assets.characters | 人物数组：name、description、personality，以及可选 identity、costumeEvidence |
| state.assets.scenes / items | 场景、物品数组：name、description |
| state.plan | 分镜大纲：index、scene、roles、summary、dialogueLines，部分含 silentBeats |
| state.frames | 已生成的分镜：index、text、videoPrompt；尚未完成的字段可能缺省 |
| projectId / projectAssets | 项目和资产库记录，含资产 id、kind、description、uploadId、imageUrl、revision |
| imageModels / imageJobs | 当前可用图片模型及最近资产生图任务 |
| storyboardDurations | 按分镜编号返回的时长 |
| frameCount / plannedCount / videoPromptCount | 已完成文案数、大纲数、描述词数 |
| needsStoryboards / needsVideoPrompts | 是否还缺文案或描述词 |

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

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

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

### 3.4 开始分镜与视频描述词

```http
POST /studio/workbench/{jobId}/storyboard
```

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

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

### 3.5 编辑、恢复和导入

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

| 路径 | JSON 正文 | 用途 |
|---|---|---|
| `/save-asset` | revision、kind、name、description；人物可加 personality | 编辑单项资产；kind 为 characters/scenes/items |
| `/save-assets` | revision、assets | 资产就绪阶段整批编辑，保留全部原始资产名称 |
| `/save-frame` | revision、index、text 和/或 videoPrompt | 编辑一条分镜，index 从 1 开始 |
| `/save` | revision、assets、storyboard | 完成后整批编辑；storyboard 为整份视频描述词文本，已导入时应在项目中编辑 |
| `/delete-asset` | revision、kind、name | 删除指定资产；处理中先等待完成 |
| `/retry` | revision | 重试失败或暂停的未完成步骤 |
| `/cancel` | {} | 停止文字处理，保留已完成内容，释放未完成冻结费用 |
| `/resume` | {} | 继续失败、暂停或取消的文字任务 |
| `/video-prompts` | {} | 恢复未完成处理，或为已完成但缺描述词的任务补全 |
| `/regenerate-video` | revision、index、requestKey | 付费重新生成指定分镜的视频描述词，保留原结果直到新结果完成 |
| `/rebuild-script` | revision、script、duration、requestKey | 复用资产创建修订任务，duration 为 15/30；requestKey 最多 60 字符 |
| `/import` | {} | 完成后同步资产与分镜至本站项目；返回 projectId、assets、shots、repeated |
| `/delete` | {} | 删除已停止的工作台记录；处理中先取消 |

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

## 4. 资产生图

### 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 去重。工作台的 `/import` 已完成关联时，直接读取返回 projectId 即可。

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

## 6. Python 接入示例

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

```python
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 的任务继续查询原编号。遇到余额不足，已完成内容会保留，充值后使用原任务恢复入口。