API Reference · v1

分镜提示词 API

面向视频生成工作流的异步接口。先生成人物卡，再逐步生成剧情线、剧本和最终分镜提示词。

Base URL http://localhost:3000

快速开始

三步完成第一次接口调用

1. 创建 Token
在主页面顶部注册或登录，每个账户最多创建 10 个 Token。

2. 创建任务
提交主题后立即得到 task_id，接口返回 202。

3. 查询结果
使用同一个 Token 和 task_id 重复请求结果接口。

任务状态
processing、succeeded 或 failed。

鉴权说明

所有用户接口都使用 Bearer Token

请求头格式如下。Token 以 ycgod- 开头，后接 32 位大小写字母或数字。

Authorization: Bearer ycgod-A7kP2mX9qL4sR8wZA7kP2mX9qL4sR8wZ

200 成功202 已创建任务400 参数错误401 Token 无效404 任务不存在

当前所有生成任务统一使用 gpt-5.6-sol，通过 OpenAI Responses API 兼容协议调用；思考程度为 high，结构化输出模式为 json_object。

创建 API Token

主页面账户功能

WEB注册 / 登录后创建已实现

在本页面外层顶部注册或登录后创建 Token。完整 Token 只显示一次，创建成功后可直接点击“复制 Token”；刷新页面后无法再次读取明文。

规则	说明
账户额度	每个账户最多保有 10 个未删除 Token；禁用仍占额度，删除后释放额度。
安全存储	服务端只保存 Token 哈希，不保存或恢复完整 Token。
旧联调地址	`GET /api/get-token` 已下线并返回 `410 Gone`。

鉴权检查

GET /api/v1/auth-check

GET/api/v1/auth-check已实现

curl

curl http://localhost:3000/api/v1/auth-check \
  -H "Authorization: Bearer $TOKEN"

响应示例 · 200

{
  "ok": true,
  "token": { "id": 1, "name": "我的 Agent" }
}

Agent MCP 与 Skill

Streamable HTTP MCP

MCP/mcp已实现

Agent 可以通过 MCP 直接完成从人物卡到镜头提示词的工作流。MCP 使用与 REST API 相同的 Bearer Token，不提供注册、Token 创建或管理端能力。

MCP 地址

https://YOUR_DOMAIN/mcp

请求头

Authorization: Bearer ycgod-你的32位随机字符

下载并安装 storyboard-workflow Skill，Agent 将遵循 Season、任务轮询、剧本分批、审查和分镜生成流程。可同时下载 SHA-256 校验文件。

创建人物卡任务

POST /api/v1/character-cards

POST/api/v1/character-cards已实现

提交主题和主要人物数量，服务端异步调用模型。characterCount 默认为 5，范围为 1-20。

请求体 · application/json

{
  "topic": "都市悬疑短剧",
  "characterCount": 5
}

响应示例 · 202

{
  "task_id": "task_8d3a9e1c742b4d6f80a5c913e247f921",
  "status": "processing"
}

curl

curl -X POST http://localhost:3000/api/v1/character-cards \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"topic":"都市悬疑短剧","characterCount":5}'

获取人物卡结果

POST /api/v1/character-cards/result

POST/api/v1/character-cards/result已实现

固定请求地址，任务通过 JSON 请求体中的 task_id 区分。模型执行期间重复调用即可轮询；服务端会在模型异常、非法 JSON 或超时后返回 failed。

请求体 · application/json

{ "task_id": "task_8d3a9e1c742b4d6f80a5c913e247f921" }

curl

curl -X POST http://localhost:3000/api/v1/character-cards/result \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"task_id":"task_8d3a9e1c742b4d6f80a5c913e247f921"}'

生成中 · 200

{
  "task_id": "task_8d3a9e1c742b4d6f80a5c913e247f921",
  "status": "processing",
  "result": null,
  "error": null
}

成功 · 200（节选）

{
  "task_id": "task_8d3a9e1c742b4d6f80a5c913e247f921",
  "status": "succeeded",
  "result": {
    "topic": "都市悬疑短剧",
    "characters": [{ "name": "林岚", "gender": "女", "age": 29 }],
    "relationship_seeds": []
  },
  "error": null
}

失败 · 200

{
  "task_id": "task_8d3a9e1c742b4d6f80a5c913e247f921",
  "status": "failed",
  "result": null,
  "error": { "code": "MODEL_INVALID_JSON", "message": "模型返回的内容不是有效 JSON" }
}

创建剧情线任务

POST /api/v1/storylines

POST/api/v1/storylines已实现

提交主题和 1-99 张完整人物卡，异步生成三幕式剧情线。请求体上限为 512 KiB；当前剧情线默认目标范围为 1500-4000 tokens。

Token 必须放在 Authorization: Bearer <token> 请求头中。创建任务时不传 task_id。

字段	类型	必填	约束
`topic`	string	是	长度 2-1000 个字符
`characterCards`	array	是	包含 1-99 张完整人物卡
`characterCards[].name`	string	是	人物姓名
`characterCards[].age`	integer	是	正整数
`characterCards[]` 其他字段	string / array	是	与人物卡接口返回的 `characters` 数组字段一致

请求体 · application/json

{
  "topic": "都市悬疑短剧",
  "characterCards": [{
    "name": "林岚",
    "gender": "女",
    "age": 29,
    "identity": "刑警",
    "appearance": "黑色短发，深色风衣",
    "personality": ["谨慎", "敏锐"],
    "strengths": ["观察力强"],
    "weaknesses": ["不信任他人"],
    "external_goal": "查明旧案真相",
    "internal_need": "学会信任同伴",
    "fear": "再次失去搭档",
    "secret": "曾隐瞒一份证据",
    "behavior_habits": ["思考时敲桌面"],
    "speech_style": "简短直接",
    "conflict_triggers": ["他人隐瞒信息"],
    "character_arc": "从孤立调查走向共同承担",
    "visual_consistency_prompt": "29岁女性，黑色短发，深色风衣"
  }]
}

curl

curl -X POST http://localhost:3000/api/v1/storylines \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @storyline-request.json

响应示例 · 202

{
  "task_id": "task_b4d72471f94246c2869ed76082c99da0",
  "status": "processing"
}

HTTP 错误

状态码	含义
`400`	请求体不是合法 JSON，或主题、人物卡数量及字段格式不正确
`401`	Bearer Token 缺失、无效、已禁用或已过期
`413`	请求体超过 512 KiB

获取剧情线结果

POST /api/v1/storylines/result

POST/api/v1/storylines/result已实现

固定请求地址。Token 继续放在 Bearer 请求头中，请求体只传创建接口返回的 task_id。

请求体 · application/json

{ "task_id": "task_b4d72471f94246c2869ed76082c99da0" }

curl

curl -X POST http://localhost:3000/api/v1/storylines/result \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"task_id":"task_b4d72471f94246c2869ed76082c99da0"}'

生成中 · 200

{
  "task_id": "task_b4d72471f94246c2869ed76082c99da0",
  "status": "processing",
  "result": null,
  "error": null,
  "created_at": "2026-08-03 10:00:00",
  "completed_at": null
}

成功 · 200

{
  "task_id": "task_b4d72471f94246c2869ed76082c99da0",
  "status": "succeeded",
  "result": {
    "topic": "都市悬疑短剧",
    "logline": "一名刑警追查旧案时被迫面对自己隐瞒的证据。",
    "genre_and_tone": "都市悬疑，克制紧张",
    "world_setting": "当代沿海城市，一宗旧案重新浮出水面。",
    "core_conflict": {
      "protagonistic_force": "林岚试图公开旧案真相",
      "opposing_force": "利益集团试图销毁证据",
      "stakes": "证人与调查人员都将失去安全",
      "dramatic_question": "真相能否在证据消失前被公开"
    },
    "added_characters": [
      {
        "name": "周衡",
        "identity": "企业危机处理负责人",
        "dramatic_function": "作为立场相反的合作者推动冲突升级",
        "relationship_to_main_characters": "林岚的调查对象与临时搭档",
        "conflict": "试图维持秩序，同时隐瞒自己参与过封锁行动"
      }
    ],
    "acts": [
      {
        "act": 1,
        "title": "旧案重启",
        "purpose": "建立人物目标并迫使双方合作",
        "story_beats": [
          { "sequence": 1, "title": "证据出现", "summary": "旧案证物重现。", "involved_characters": ["林岚"], "conflict": "林岚必须隐瞒自己的过错。", "consequence": "调查重新启动。" },
          { "sequence": 2, "title": "被迫合作", "summary": "林岚与周衡共同调查。", "involved_characters": ["林岚", "周衡"], "conflict": "二人对公开信息的立场相反。", "consequence": "双方开始互相试探。" },
          { "sequence": 3, "title": "第一次追杀", "summary": "证人遭到袭击。", "involved_characters": ["林岚", "周衡"], "conflict": "救人还是保护证据。", "consequence": "二人无法退出调查。" }
        ],
        "turning_point": "林岚发现周衡参与过当年的封锁。"
      },
      {
        "act": 2,
        "title": "秘密反噬",
        "purpose": "升级外部危险并击碎人物信任",
        "story_beats": [
          { "sequence": 1, "title": "交换秘密", "summary": "二人交换部分情报。", "involved_characters": ["林岚", "周衡"], "conflict": "双方都保留关键事实。", "consequence": "调查取得进展但信任更加脆弱。" },
          { "sequence": 2, "title": "证据断裂", "summary": "关键数据库被清除。", "involved_characters": ["林岚", "周衡"], "conflict": "双方互相怀疑泄密。", "consequence": "合作关系破裂。" },
          { "sequence": 3, "title": "真相曝光", "summary": "林岚删除录像的事实被发现。", "involved_characters": ["林岚", "周衡"], "conflict": "个人罪责与公共真相发生冲突。", "consequence": "林岚失去调查资格。" }
        ],
        "turning_point": "周衡决定违背公司命令帮助林岚。"
      },
      {
        "act": 3,
        "title": "公开代价",
        "purpose": "解决核心冲突并完成人物选择",
        "story_beats": [
          { "sequence": 1, "title": "最后取证", "summary": "二人潜入封存中心。", "involved_characters": ["林岚", "周衡"], "conflict": "时间不足且追兵逼近。", "consequence": "完整证据被恢复。" },
          { "sequence": 2, "title": "共同选择", "summary": "二人决定公开全部事实。", "involved_characters": ["林岚", "周衡"], "conflict": "公开意味着二人都将获罪。", "consequence": "证据被发送给公众。" },
          { "sequence": 3, "title": "承担后果", "summary": "真相引发调查和审判。", "involved_characters": ["林岚", "周衡"], "conflict": "二人必须接受各自责任。", "consequence": "旧案得到重审。" }
        ],
        "turning_point": "林岚公开承认自己的过错。"
      }
    ],
    "character_arcs": [
      { "character_name": "林岚", "starting_state": "拒绝信任他人", "key_choices": ["向周衡坦白", "公开自己的罪责"], "ending_state": "愿意共同承担真相的代价" }
    ],
    "relationship_development": [
      { "characters": ["林岚", "周衡"], "initial_state": "敌对合作", "conflict_progression": "从立场对立到秘密曝光后的决裂", "final_state": "互相信任并共同承担责任" }
    ],
    "ending": "真相被公开，旧案重审，林岚与周衡分别承担法律责任。",
    "unresolved_hooks": ["幕后利益集团仍有成员未被查明"]
  },
  "error": null,
  "created_at": "2026-08-03 10:00:00",
  "completed_at": "2026-08-03 10:01:06"
}

失败 · 200

{
  "task_id": "task_b4d72471f94246c2869ed76082c99da0",
  "status": "failed",
  "result": null,
  "error": {
    "code": "MODEL_INVALID_JSON",
    "message": "模型返回的剧情线格式不正确，请重新创建任务"
  },
  "created_at": "2026-08-03 10:00:00",
  "completed_at": "2026-08-03 10:01:06"
}

HTTP 错误

状态码	含义
`400`	`task_id` 格式不正确
`401`	Bearer Token 缺失、无效、已禁用或已过期
`404`	任务不存在、任务类型不匹配，或任务不属于当前 Token

绑定剧集项目

POST /api/v1/seasons/bind

POST/api/v1/seasons/bind已实现

将当前 Token 名下已成功的人物卡任务和剧情线任务绑定为一个长期使用的剧集项目。传入 season_id 时绑定到已创建的空项目；不传时自动创建或复用 Season。

season_id 是后续剧本、审查、修订和分镜资源的统一项目 ID。接口会保存人物卡和剧情线结果快照；重复绑定同一组任务会返回原有 season_id。

请求体 · application/json

{
  "season_id": "season_7a91b23c4d5e4f67890123456789abcd",
  "character_task_id": "task_11111111111111111111111111111111",
  "storyline_task_id": "task_22222222222222222222222222222222",
  "season_name": "都市悬疑短剧"
}

curl

curl -X POST http://localhost:3000/api/v1/seasons/bind \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "season_id":"season_7a91b23c4d5e4f67890123456789abcd",
    "character_task_id":"task_11111111111111111111111111111111",
    "storyline_task_id":"task_22222222222222222222222222222222",
    "season_name":"都市悬疑短剧"
  }'

首次绑定 · 201

{
  "season_id": "season_7a91b23c4d5e4f67890123456789abcd",
  "season_name": "都市悬疑短剧",
  "status": "ready",
  "character_task_id": "task_11111111111111111111111111111111",
  "storyline_task_id": "task_22222222222222222222222222222222",
  "created": false,
  "bound": true
}

重复绑定 · 200

{
  "season_id": "season_7a91b23c4d5e4f67890123456789abcd",
  "season_name": "都市悬疑短剧",
  "status": "ready",
  "character_task_id": "task_11111111111111111111111111111111",
  "storyline_task_id": "task_22222222222222222222222222222222",
  "created": false,
  "bound": false
}

HTTP 错误

状态码	含义
`400`	任务 ID 格式不正确，或任务类型与字段不匹配
`401`	Bearer Token 缺失、无效、已禁用或已过期
`404`	任务不存在，或任务不属于当前 Token
`409`	人物卡或剧情线任务尚未成功，或没有可绑定的结果
`409`	指定 Season 已绑定其他资源，或相同任务组合已绑定到其他 Season

创建剧集项目

POST /api/v1/seasons

POST/api/v1/seasons已实现

在人物卡和剧情线生成前创建一个空的 Season。之后调用绑定接口并传入该 season_id，即可把成功任务绑定到这个项目。

curl -X POST http://localhost:3000/api/v1/seasons \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"season_name":"都市悬疑短剧"}'

成功响应 · 201

{
  "season_id": "season_7a91b23c4d5e4f67890123456789abcd",
  "season_name": "都市悬疑短剧",
  "status": "ready",
  "created": true
}

获取剧集项目

GET /api/v1/seasons

GET/api/v1/seasons已实现

使用 Bearer Token 获取该 Token 名下已经创建的全部 Season，无需请求体。task_ids 返回各类当前资源绑定的来源任务 ID。

curl http://localhost:3000/api/v1/seasons \
  -H "Authorization: Bearer $TOKEN"

成功响应 · 200

{
  "seasons": [
    {
      "season_id": "season_7a91b23c4d5e4f67890123456789abcd",
      "season_name": "都市悬疑短剧",
      "status": "READY",
      "task_ids": {
        "character_cards": "task_11111111111111111111111111111111",
        "storyline": "task_22222222222222222222222222222222",
        "script": "task_33333333333333333333333333333333",
        "script_review": null,
        "storyboard": null
      },
      "created_at": "2026-08-03 07:01:51",
      "updated_at": "2026-08-03 07:01:51"
    }
  ]
}

分批生成剧本

POST /api/v1/scripts

POST/api/v1/scripts已实现

首次调用根据 Season 资料生成全剧场次规划；后续使用同一 season_id 重复调用，每次生成下一批最多 2 场。默认目标 30000 字，范围 1000-80000 字，目标字数只在首次调用时确定。

请求体

{
  "season_id": "season_7a91b23c4d5e4f67890123456789abcd",
  "target_word_count": 30000
}

响应 · 202

{
  "task_id": "task_33333333333333333333333333333333",
  "status": "processing",
  "season_id": "season_7a91b23c4d5e4f67890123456789abcd",
  "script_id": "script_44444444444444444444444444444444",
  "script_status": "planning"
}

curl

curl -X POST http://localhost:3000/api/v1/scripts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"season_id":"season_7a91b23c4d5e4f67890123456789abcd","target_word_count":30000}'

POST/api/v1/scripts/result已实现

用创建接口返回的 task_id 轮询。规划成功时返回 script_status: ready；批次成功时返回场次范围和下一场编号；最后一批返回 script_status: all_done。

curl -X POST http://localhost:3000/api/v1/scripts/result \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"task_id":"task_33333333333333333333333333333333"}'

获取全剧规划

POST /api/v1/scripts/plan

POST/api/v1/scripts/plan已实现

同步读取首次剧本任务生成的全剧场次规划，不创建新任务，也不会改变当前剧本生成状态。Token 使用 Bearer 鉴权，请求体只传 season_id。

curl -X POST http://localhost:3000/api/v1/scripts/plan \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"season_id":"season_7a91b23c4d5e4f67890123456789abcd"}'

成功响应 · 200

{
  "season_id": "season_7a91b23c4d5e4f67890123456789abcd",
  "script_id": "script_44444444444444444444444444444444",
  "script_status": "ready",
  "target_word_count": 30000,
  "total_scenes": 30,
  "plan": {
    "title": "剧名",
    "scene_plan": []
  }
}

剧本项目不存在或不属于当前 Token 时返回 404；首次规划尚未成功时返回 409 SCRIPT_PLAN_NOT_READY。

分页读取剧本

POST /api/v1/scripts/content

POST/api/v1/scripts/content已实现

读取当前剧本版本中已经成功提交的场次。生成失败的批次不会写入场次，也不会推进下一场编号。page_size 默认为 20，最大 100。

curl -X POST http://localhost:3000/api/v1/scripts/content \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"season_id":"season_7a91b23c4d5e4f67890123456789abcd","page":1,"page_size":20}'

响应字段

script_status、target_word_count、generated_word_count、generated_scenes、total_scenes、scenes 和 pagination。

审查与修订剧本

仅在全剧生成完成后使用

POST/api/v1/scripts/reviews已实现

完整读取当前版本剧本，异步返回结构、人物、连续性和 callback 修改建议，不直接修改剧本。

curl -X POST http://localhost:3000/api/v1/scripts/reviews \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"season_id":"season_7a91b23c4d5e4f67890123456789abcd"}'

接口返回 task_id，使用下一个接口查询审查状态和修改建议。

POST/api/v1/scripts/reviews/result已实现

使用创建审查任务返回的 task_id 查询状态；成功后返回 review_id 和可供确认的修改建议。

curl -X POST http://localhost:3000/api/v1/scripts/reviews/result \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"task_id":"task_66666666666666666666666666666666"}'

POST/api/v1/scripts/review-confirm已实现

采纳审查建议 ID 和/或填写自定义意见。修订成功后创建新的完整剧本版本，旧版本保留；content 接口自动读取新版本。

curl -X POST http://localhost:3000/api/v1/scripts/review-confirm \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "season_id":"season_7a91b23c4d5e4f67890123456789abcd",
    "review_id":"review_55555555555555555555555555555555",
    "accepted_suggestion_ids":["suggestion_001"],
    "custom_instructions":"加强最终场的情绪回收"
  }'

接口返回 task_id，使用下一个接口查询修订状态和新版本信息。

POST/api/v1/scripts/review-confirm/result已实现

使用确认修改接口返回的 task_id 查询修订状态；成功后，分页读取剧本接口会自动返回最新版本。

curl -X POST http://localhost:3000/api/v1/scripts/review-confirm/result \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"task_id":"task_77777777777777777777777777777777"}'

剧集规划

POST /api/v1/episode-plans

POST/api/v1/episode-plans已实现

全剧生成完成后，按单集目标时长和可选集数拆分剧本，不新增或改写剧情。

{
  "season_id": "season_7a91b23c4d5e4f67890123456789abcd",
  "target_episode_duration_seconds": 60,
  "target_episode_count": 60
}

POST/api/v1/episode-plans/result已实现

Bearer Token 鉴权，请求体只传创建接口返回的 task_id。

镜头规划

POST /api/v1/shot-plans

POST/api/v1/shot-plans已实现

为剧集规划中的指定集生成连续时间轴、情绪目的、景别、机位、构图和运镜规划。单镜头最长时间是第三方平台硬上限，不限制更短镜头。

{
  "season_id": "season_7a91b23c4d5e4f67890123456789abcd",
  "episode_number": 1,
  "max_shot_duration_seconds": 5
}

POST/api/v1/shot-plans/result已实现

查询任务成功后得到该集的全部 shot_id，后续提示词必须使用当前镜头规划版本的 ID。

镜头提示词

POST /api/v1/shot-prompts

POST/api/v1/shot-prompts已实现

一次为 1-50 个镜头生成自包含、可直接提交视频模型的 complete_prompt Markdown。局部重做时只传不满意的镜头，并填写修改意见。

{
  "shot_ids": ["shot_11111111111111111111111111111111"],
  "regeneration_instruction": "减少环境描述，强调人物手部动作和视线方向"
}

POST/api/v1/shot-prompts/result已实现

成功结果按 shot_id 返回完整提示词，不需要用户二次拼接。