StarReel Production APIStarReel 短剧产线 API

Turn a script into a finished, downloadable short-drama episode — programmatically. Drive the whole pipeline (storyboards → frames → video → final cut) from an AI agent over MCP, or from your own code over REST. One key powers both. 把剧本变成一集可下载的成片 — 全程可编程。用 AI agent 走 MCP,或从你自己的代码走 REST,驱动整条产线(分镜 → 帧 → 视频 → 成片)。一把 Key 通用。

The pipeline产线一览

One episode, the full pipeline — nothing skipped. Set the raw script, let AI rewrite it into a shootable draft (you can review & edit), extract the cast/scenes/props, lock character portraits (the consistency anchor), then storyboards → frames → video → final cut. Each spending stage gives you a quote first; you confirm, then it runs in the background. 一集短剧,走完整工作流、不跳步。设原始剧本 → AI 改写成可拍稿(可审阅/改稿)→ 提取角色/场景/道具 → 锁角色定妆图(一致性锚)→ 分镜 → 首帧 → 视频 → 成片。每个花钱阶段先报价,你确认后后台执行。

剧本  create_drama → set_script(原始) → rewrite_script(AI改写) → [get_script / edit_rewritten_script]
      → extract_assets(角色/场景/道具) → generate_portraits_and_sheets(定妆图+设定图) → assign_voices(分配音色·配音前必做)
制作  → storyboards → frames → videos → compose → 成片.mp4(COS 下载链接)

免费(DB/ffmpeg):create_drama · set_script · get_* · edit · update设定 · compose · 多画幅 · 音效/特效/转场 · 交付物      按量后付·无报价(不足即402):rewrite · extract · tts配音 · 海报/封面/三视图 · 世界观/美术/色彩/动作等风格锁 · MV故事/剧本
报价·确认(quote_* + generate_*):storyboards · frames · videos · character_portraits · scene_images
项目类型:create_drama 传 project_type = drama(短剧) / ad(商业广告) / mv(音乐) / brand_film(品牌短片)
★广告(ad)专属必做:add_product 建产品库(广告主体)+ generate_product_sheet 出设定图,否则镜头产品漂移;MV:set_mv_lyrics→generate_mv_story→generate_mv_script
get_pipeline_status 按项目类型返回专属步骤(广告 build_product_library/set_cta,MV 歌词/故事)——查它就知道还差什么

Both paths share the same key, scopes, and billing (below). Base URL: https://api.shortreelai.com两条路径共用同一套 Key、scope 与计费(见下)。基址:https://api.shortreelai.com

Authentication鉴权

Create a long-lived API key in Settings → API Key (srk_live_…, shown once). You never send the key to business endpoints — you exchange it for a short 15-minute bearer token, then send that token. Re-exchange when it expires. 在 设置 → API Key 创建长期 Key(srk_live_…,只显示一次)。Key 不直接调业务端点 — 先换一枚 15 分钟短期令牌,再带令牌调用。过期就重新换。

curl -X POST https://api.shortreelai.com/v1/agent/token \
  -H 'content-type: application/json' \
  -d '{"api_key":"srk_live_..."}'

# 200
{ "code": 0, "data": {
    "access_token": "eyJ...",
    "token_type": "Bearer",
    "expires_in": 900,
    "scopes": "produce,read" } }

import time, requests

BASE = "https://api.shortreelai.com"
API_KEY = "srk_live_..."
_tok = {"v": None, "exp": 0}

def token():
    """Exchange the API key for a 15-min token, cached until ~1 min before expiry."""
    if _tok["v"] and time.time() < _tok["exp"] - 60:
        return _tok["v"]
    r = requests.post(f"{BASE}/v1/agent/token", json={"api_key": API_KEY})
    r.raise_for_status()
    d = r.json()["data"]
    _tok["v"] = d["access_token"]
    _tok["exp"] = time.time() + d["expires_in"]
    return _tok["v"]

def auth():
    return {"authorization": f"Bearer {token()}"}

const BASE = "https://api.shortreelai.com";
const API_KEY = "srk_live_...";
let _tok = { v: null, exp: 0 };

// Exchange the API key for a 15-min token, cached until ~1 min before expiry.
export async function token() {
  if (_tok.v && Date.now() < _tok.exp - 60000) return _tok.v;
  const r = await fetch(BASE + "/v1/agent/token", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ api_key: API_KEY }),
  });
  if (!r.ok) throw new Error("token exchange failed: " + r.status);
  const d = (await r.json()).data;
  _tok = { v: d.access_token, exp: Date.now() + d.expires_in * 1000 };
  return _tok.v;
}
export const auth = async () => ({ authorization: "Bearer " + (await token()) });

Scopes授权范围

A key's power is set by the scopes you pick when creating it. Out-of-scope calls return 403.Key 权限由创建时选的 scope 决定,越权返回 403。

Billing — prepaid, no overdraft计费 — 先充值,不欠费

StarReel is prepaid. You need balance to generate, and the account never goes negative. Cost is authorized against your balance before the vendor runs; if you can't afford it the call returns 402 and no vendor cost is incurred. When the balance runs out mid-use, the account stops until you recharge. Usage is billed to the same balance as the web app. StarReel 预付制。生成需有余额,账户永不为负。成本在厂商运行之前对余额预授权;付不起则 402 且不产生厂商成本。余额用尽即停,充值后恢复。用量计入与网页端同一套余额。

Path A · MCP setup路径A · MCP 接入

For AI agents. After setup, the agent discovers and calls the tools on its own — you just talk to it.给 AI agent。接入后 agent 自行发现并调用工具 — 你只管对它说话。

Claude Code

claude mcp add starreel -e STARREEL_API_KEY=srk_live_... -- npx -y @starreel/mcp

Cursor / other MCP clientsCursor / 其他 MCP 客户端

Add to your client's MCP config (e.g. mcp.json):加进客户端的 MCP 配置(如 mcp.json):

{
  "mcpServers": {
    "starreel": {
      "command": "npx",
      "args": ["-y", "@starreel/mcp"],
      "env": { "STARREEL_API_KEY": "srk_live_..." }
    }
  }
}

MCP tools — the pipelineMCP 工具 — 整条产线

Needs produce scope. Follow the full workflow in order — poll get_pipeline_status to see the 10 stages. Big-ticket stages (portraits / storyboards / frames / videos / scene-images) split into quote_* + generate_* so the agent shows you the quote first; other AI-generation steps have no quote — they meter by usage and return 402 mid-run if the balance can't cover them (never overdraft). Long stages run in the background.需 produce scope。照完整工作流按序推进,用 get_pipeline_status 看 10 步进度。大额阶段(定妆图/分镜/首帧/视频/场景图)拆成 quote_* + generate_*,agent 先给你报价;其余 AI 生成步无报价,按用量后付、余额不足执行中 402(不欠费)。长阶段后台异步。

Every MCP tool maps 1:1 to a REST endpoint under /v1/produce/* (same names, same params). The REST reference below covers authentication and the core flow; the tools above are the full surface.每个 MCP 工具与 /v1/produce/* 下的一个 REST 端点一一对应(同名同参)。下面 REST 章节讲鉴权与主干流程;上表即完整工具面。

Agent skill & disciplinesAI agent 操作 Skill 与纪律

A drop-in operating skill for any AI agent driving this pipeline — the ordered workflow, ten hard disciplines, and the one failure decision. It keeps an agent on the full pipeline, inside budget, compliant, and correct when a shot fails. 给任何驱动本产线的 AI agent 的一份即插即用操作 Skill — 完整工作流顺序、十条硬纪律、失败时的唯一决策。让 agent 照产线走、不超支、不违规、镜头失败时判得对。

The ten disciplines十条纪律

1. Prepaid, never overdraft.先充值,永不欠费。 On 402 insufficient_credits, stop and ask the user to recharge — never loop-retry a 402; it can't succeed.遇 402 insufficient_credits 立即停并提示充值 — 绝不循环重试 402,它不可能成功。
2. Quote before you spend; the quote is the charge.先报价再花钱;报价即扣费。 Big-ticket stages (portraits / storyboards / frames / videos / scene-images) are quote_* then generate_* — show the quote first. Other AI-generation steps (TTS, posters, sheets, style locks …) have no quote but still bill by usage. Show the user before any spend; don't auto-approve large ones.大额阶段(定妆图/分镜/首帧/视频/场景图)是 quote_* 后 generate_*——先报价。其余 AI 生成步(TTS、海报、三视图、风格锁…)无报价但按用量照样收费。任何花钱前先告知用户;不替用户默认同意大额。
3. retryable decides retry-vs-change.retryable 一锤定音:重试还是改内容。 false (moderation / copyright / quota / overdue) → change content or stop; true (KYC-queue / rate-limit / transient) → back off, retry. Never blind-retry.false(审核/版权/配额/欠费)→ 改内容或停;true(KYC 排队/限流/偶发)→ 退避后重试。绝不盲目重试。
4. Content must be compliant.内容必须合规。 No copyrighted characters, trademarks, real-person likenesses, or sensitive content. On rejection, rewrite toward generic, original imagery — don't fight the gate.不生成版权角色、商标、真人特征或敏感内容。命中拒收就改成通用原创形象 — 不硬刚审核门。
5. Voice cloning needs consent.声音克隆须授权。 Only clone a sample the user is authorized to use (own voice or rights-holder consent). Never clone a third party's voice without permission.只克隆用户有权使用的样本(本人或持权人同意)。绝不未经授权克隆第三方声音。
6. Follow the order; don't skip.照顺序走,不跳步。 Lock character portraits and sheets and frames before video — portraits alone leave characters drifting (sheets are the shot consistency anchor); no first frame degrades to anchorless t2v. Both waste money.出视频前先锁定妆图和设定图和首帧——只出定妆图人物会漂(设定图才是镜头一致性根锚);无首帧退化无锚点 t2v。都白花钱。
7. Poll, don't block or hammer.轮询,别阻塞也别打爆。 Long steps are async; poll get_pipeline_status / get_jobs / get_storyboards with backoff. Stable counts = done.长步骤异步;带退避轮询 get_pipeline_status / get_jobs / get_storyboards。数量稳定=完成。
8. Idempotency — don't double-charge.幂等 — 不重复扣费。 A quote_id is one-time (~15 min). Never generate_* the same intent twice; read current state before regenerating.quote_id 一次性(约 15 分钟)。同一意图绝不 generate_* 两次;重生前先读现状。
9. Stay in your tenant.只碰自己的资源。 Someone else's id returns 404 by design (probes never leak existence). Don't guess ids.别人的 id 一律 404(探测不泄漏存在性)。别猜 id。
10. Be transparent; keep secrets safe.对用户透明;守好密钥。 Report the quote, the failure reason, and actual spend — never fake success. Keep the API key in env / secrets, never in code or logs.如实呈现报价、失败原因、实际花费 — 绝不伪造成功。API key 放环境变量/密钥管理,绝不进代码或日志。
11. Content is the user's, not yours.内容属于用户,不是你编的。 Never invent character names, titles, or dialogue — drive the pipeline from the user's script and choices.绝不自行编造角色名、剧名或台词 — 一切以用户的剧本与选择驱动产线。

Drop-in skill — copy into any agent's system prompt可整段复制 — 贴进任意 agent 的 system prompt

You are an agent driving StarReel, a PREPAID AI short-drama pipeline. You turn a
raw script into a downloadable episode via StarReel tools/endpoints.

PIPELINE (full, never skip):
create_drama → set_script(raw) → rewrite_script → extract_assets →
generate_portraits_and_sheets → storyboards → frames → videos →
generate_tts → compose_episode → final cut. Always generate frames BEFORE
videos. project_type = drama/ad/mv/brand_film (call list_project_options first).

TEN DISCIPLINES:
1. Prepaid, never overdraft. On 402 insufficient_credits, STOP and ask the user
   to recharge. Never loop-retry a 402.
2. Quote before you spend; the quote is the charge. Big-ticket stages
   (portraits/storyboards/frames/videos/scene-images) are quote_* then generate_*;
   other AI steps (TTS/posters/sheets/style locks) have no quote but still bill.
   Show the user before any spend; don't auto-approve large ones.
3. retryable decides retry-vs-change. false (moderation/copyright/quota/overdue)
   → change content or stop. true (KYC/rate-limit/transient) → back off, retry.
   Never blind-retry.
4. Content must be compliant. No copyrighted characters, trademarks, real-person
   likenesses, or sensitive content. On rejection, rewrite toward generic
   original imagery; do not fight the gate.
5. Voice cloning needs consent. Only clone a sample the user is authorized to
   use. Never clone a third party's voice without permission.
6. Follow the order; do not skip. Lock portraits and frames before video, or
   video degrades to anchorless t2v (wasted money).
7. Poll, do not block or hammer. Long steps are async; poll get_pipeline_status
   / get_jobs / get_storyboards with backoff. Stable counts = done.
8. Idempotency. A quote_id is one-time (~15 min). Never double-generate the same
   intent. Read current state before regenerating.
9. Stay in your tenant. Others' ids return 404 by design. Do not guess ids.
10. Be transparent; keep secrets safe. Report quote, failure reason, and actual
    spend; never fake success. Keep the API key in env, never in code or logs.

ON FAILURE: read message / fail_reason / retryable.
moderation | identity | copyright → change content;
overdue | token → not self-healable (tell user / wait);
network | timeout | transient → retry. Failed spends are auto-refunded.

Docs: https://api.shortreelai.com/docs/mcp

These disciplines apply to REST integrations too — the same billing, moderation, and tenancy rules hold on /v1/produce/*.这些纪律同样适用于 REST 接入 — /v1/produce/* 上的计费、审核、租户规则完全一致。

Path B · REST API路径B · REST API

Plain HTTPS from any language. Every request carries the bearer token from Authentication. Switch the code samples with the curl / Python / Node.js selector at the top right. 任意语言的普通 HTTPS。每个请求带 鉴权换来的令牌。用右上角 curl / Python / Node.js 切换示例语言。

Base URL & response format基址与响应格式

• Base: https://api.shortreelai.com基址:https://api.shortreelai.com
• Every response is wrapped as { "code": 0, "data": {…} }; a non-zero code plus HTTP 4xx/5xx means error.响应统一包成 { "code": 0, "data": {…} };code 非 0 且 HTTP 4xx/5xx 即错误。
• Auth helper (token() / auth()) is the one from Authentication — reused in every example below.下面示例里的 token() / auth() 就是 鉴权那节的助手,全程复用。

Account账户

# identity
curl -H "authorization: Bearer $TOKEN" \
  https://api.shortreelai.com/v1/me

# plan + spendable balance
curl -H "authorization: Bearer $TOKEN" \
  https://api.shortreelai.com/v1/entitlement
# 200 -> { "code":0, "data":{ "allowed":true, "plan":"pro",
#          "spendable":42000, "credits_balance":42000 } }

me = requests.get(f"{BASE}/v1/me", headers=auth()).json()["data"]
ent = requests.get(f"{BASE}/v1/entitlement", headers=auth()).json()["data"]
print(me["email"], "balance:", ent["spendable"])

const me  = await (await fetch(BASE + "/v1/me", { headers: await auth() })).json();
const ent = await (await fetch(BASE + "/v1/entitlement", { headers: await auth() })).json();
console.log(me.data.email, "balance:", ent.data.spendable);

Pipeline endpoints产线端点

All under /v1/produce/*, need produce scope. Spending stages follow one pattern: quote → confirm → poll. The quote returns a quote_id and the estimated points; show the user, then pass the quote_id to the matching generate call. Long stages run in the background. 全在 /v1/produce/* 下,需 produce scope。花钱阶段一个套路:报价 → 确认 → 轮询。报价返回 quote_id 和预估点数;给用户看,再把 quote_id 传给对应的 generate。长阶段后台异步。

Every response is wrapped as { "code": 0, "data": {…} }.响应统一包成 { "code": 0, "data": {…} }。

Quote → confirm → poll报价 → 确认 → 轮询

The video stage, shown three ways. Frames and storyboards work identically — just change the path segment. 以视频阶段为例(三种语言)。帧和分镜用法一样 — 改路径段即可。

# 1) quote — returns estimated_points + quote_id
Q=$(curl -s -X POST https://api.shortreelai.com/v1/produce/episodes/250/videos/quote \
  -H "authorization: Bearer $TOKEN")
echo "$Q"   # { "data": { "estimated_points": 1059, "quote_id": "q_..." } }

# 2) show the user the points, then confirm with the quote_id
QID=$(echo "$Q" | jq -r .data.quote_id)
curl -s -X POST https://api.shortreelai.com/v1/produce/episodes/250/videos/generate \
  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d "{"quote_id":"$QID"}"          # -> { "data": { "status": "generating" } }

# 3) poll until every shot has a video_url
curl -s -H "authorization: Bearer $TOKEN" \
  https://api.shortreelai.com/v1/produce/episodes/250/storyboards

def stage(ep, name, poll_field=None):
    q = requests.post(f"{BASE}/v1/produce/episodes/{ep}/{name}/quote", headers=auth()).json()["data"]
    print(f"{name}: {q['estimated_points']} credits")     # show the user, get their OK
    requests.post(f"{BASE}/v1/produce/episodes/{ep}/{name}/generate",
                  headers=auth(), json={"quote_id": q["quote_id"]})
    while poll_field:                                     # poll storyboards until ready
        sbs = requests.get(f"{BASE}/v1/produce/episodes/{ep}/storyboards", headers=auth()).json()["data"]
        if sbs and all(s.get(poll_field) for s in sbs): break
        time.sleep(10)

stage(250, "frames", poll_field="first_frame_image")
stage(250, "videos", poll_field="video_url")

async function stage(ep, name, pollField) {
  const q = (await (await fetch(`${BASE}/v1/produce/episodes/${ep}/${name}/quote`,
    { method: "POST", headers: await auth() })).json()).data;
  console.log(`${name}: ${q.estimated_points} credits`);   // show the user, get their OK
  await fetch(`${BASE}/v1/produce/episodes/${ep}/${name}/generate`,
    { method: "POST", headers: { ...(await auth()), "content-type": "application/json" },
      body: JSON.stringify({ quote_id: q.quote_id }) });
  while (pollField) {
    const sbs = (await (await fetch(`${BASE}/v1/produce/episodes/${ep}/storyboards`,
      { headers: await auth() })).json()).data;
    if (sbs.length && sbs.every(s => s[pollField])) break;
    await new Promise(r => setTimeout(r, 10000));
  }
}
await stage(250, "frames", "first_frame_image");
await stage(250, "videos", "video_url");

Full run — script to download link整条跑通 — 从剧本到下载链接

# create -> set script -> storyboards -> frames -> videos -> compose -> download
# (each stage: quote, then generate with the quote_id; poll between stages)
# see the Python / Node tabs for a runnable end-to-end script.

d = requests.post(f"{BASE}/v1/produce/dramas", headers=auth(),
                  json={"title": "My Drama", "total_episodes": 1}).json()["data"]
ep = d["episodes"][0]["episode_id"]
requests.put(f"{BASE}/v1/produce/episodes/{ep}/script", headers=auth(),
             json={"script_content": my_script})
stage(ep, "storyboards", poll_field=None)      # background; poll get_storyboards for shots
# ... wait for storyboards, then:
stage(ep, "frames", poll_field="first_frame_image")
stage(ep, "videos", poll_field="video_url")
requests.post(f"{BASE}/v1/produce/episodes/{ep}/compose", headers=auth())
while True:
    fc = requests.get(f"{BASE}/v1/produce/episodes/{ep}/final-cut", headers=auth()).json()["data"]
    if fc.get("download_url"): print("done:", fc["download_url"]); break
    time.sleep(8)

const d = (await (await fetch(`${BASE}/v1/produce/dramas`, { method: "POST",
  headers: { ...(await auth()), "content-type": "application/json" },
  body: JSON.stringify({ title: "My Drama", total_episodes: 1 }) })).json()).data;
const ep = d.episodes[0].episode_id;
await fetch(`${BASE}/v1/produce/episodes/${ep}/script`, { method: "PUT",
  headers: { ...(await auth()), "content-type": "application/json" },
  body: JSON.stringify({ script_content: myScript }) });
await stage(ep, "storyboards");                 // then poll get_storyboards
await stage(ep, "frames", "first_frame_image");
await stage(ep, "videos", "video_url");
await fetch(`${BASE}/v1/produce/episodes/${ep}/compose`, { method: "POST", headers: await auth() });
let fc;
do { await new Promise(r => setTimeout(r, 8000));
  fc = (await (await fetch(`${BASE}/v1/produce/episodes/${ep}/final-cut`,
    { headers: await auth() })).json()).data;
} while (!fc.download_url);
console.log("done:", fc.download_url);

Upload your own images (portraits, frames, scenes, props)上传自有图片(定妆图/首帧/场景/道具)

Bring your own reference art instead of AI-generating it. The headline case is character portraits: an uploaded portrait becomes that character's identity anchor (source user_upload, priority over AI — later AI regens won't overwrite it), auto-invalidates & rebuilds derived assets (character sheet, hair/body refs) and registers a face-lock. Shot frames / scene images / prop sheets work the same way. 用你自己的参考图,而不是 AI 生成。最典型是角色定妆图:上传的定妆图成为该角色的身份锚(来源 user_upload,优先级高于 AI — 之后 AI 重生默认不覆盖),并自动失效重建派生资产(三视图设定图、发型/身材参考)、登记人脸锁。首帧/场景图/道具设定图同理。

REST — three steps: presign → PUT the bytes straight to COS → register.REST — 三步:拿预签名 → PUT 字节直传 COS → 登记。

# 1) presign — 拿直传 URL(图片字节不过业务服务器)
curl -X POST https://api.shortreelai.com/v1/produce/upload-url \
  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"filename":"portrait.jpg","content_type":"image/jpeg","size":204800,"kind":"image"}'
# 200 -> { "code":0, "data":{ "put_url":"https://cos...", "public_url":"https://cos.../portrait.jpg",
#          "headers":{"content-type":"image/jpeg"} } }

# 2) 用 put_url PUT 文件字节(带 data.headers 里要求的头)
curl -X PUT "$PUT_URL" -H 'content-type: image/jpeg' --data-binary @portrait.jpg

# 3) 用 public_url 登记为该角色定妆图(身份锚)
curl -X POST https://api.shortreelai.com/v1/produce/characters/42/portrait \
  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"image_url":"https://cos.../portrait.jpg"}'

pre = requests.post(f"{BASE}/v1/produce/upload-url", headers=auth(), json={
    "filename": "portrait.jpg", "content_type": "image/jpeg",
    "size": 204800, "kind": "image"}).json()["data"]
requests.put(pre["put_url"], data=open("portrait.jpg", "rb").read(),
             headers=pre.get("headers") or {"content-type": "image/jpeg"})
requests.post(f"{BASE}/v1/produce/characters/42/portrait", headers=auth(),
              json={"image_url": pre["public_url"]})

const pre = (await (await fetch(BASE + "/v1/produce/upload-url", {
  method: "POST", headers: { ...(await auth()), "content-type": "application/json" },
  body: JSON.stringify({ filename: "portrait.jpg", content_type: "image/jpeg",
    size: 204800, kind: "image" }) })).json()).data;
await fetch(pre.put_url, { method: "PUT",
  headers: pre.headers || { "content-type": "image/jpeg" }, body: fileBytes });
await fetch(BASE + "/v1/produce/characters/42/portrait", {
  method: "POST", headers: { ...(await auth()), "content-type": "application/json" },
  body: JSON.stringify({ image_url: pre.public_url }) });

The same upload-url presign works for any image / video / audio; register with the matching endpoint (/storyboards/:id/frame, /scenes/:id/image, /props/:id/sheet). Uploads are free — you only pay when you later generate from them.同一个 upload-url 预签名适用于任意图片/视频/音频,再用对应端点登记(/storyboards/:id/frame、/scenes/:id/image、/props/:id/sheet)。上传免费 — 只有之后据它生成才计费。

Troubleshooting常见问题处理

Every failure surfaces as a human-readable message (the MCP client throws Error(message); REST returns { code, message } or, on the metered /v1/ai/* layer, { error: { message, type, needed?, retryable? } }). The message is written for your agent to act on — read it, don't blindly retry. Failed spends are auto-refunded (pre-hold → refund on failure), so you never need to compensate manually.所有失败都带一段人类可读的 message(MCP 客户端抛 Error(message);REST 返回 { code, message },计费层 /v1/ai/* 返回 { error: { message, type, needed?, retryable? } })。这段 message 是给 agent 行动用的 —— 照它做,别盲目重试。失败的扣费一律自动退款(预扣→失败退款),不用手动补偿。

★ Shot images / videos: rejected vs. failed — how to tell & what to do★ 镜头图片 / 视频:拒收 vs 失败 —— 怎么判、怎么办

Generation is async: call generate_frames / generate_videos, then poll get_storyboards. Each shot now carries structured status so you don't parse text: frame_status / video_status (ready/pending/authorizing/rejected/failed/none), fail_reason (the enum in the table below), retryable (the one flag that decides retry-vs-change), and fail_hint (human message). Retrying a rejection is useless; retrying a transient failure is correct.生成是异步的:调 generate_frames / generate_videos 后轮询 get_storyboards。每镜现在直接带结构化状态,不用解析文案:frame_status / video_status(ready/pending/authorizing/rejected/failed/none)、fail_reason(下表的枚举)、retryable(一锤定音:该重试还是该改)、fail_hint(人读文案)。拒收去重试是白费;偶发失败去重试才对。

The one signal that decides it: the retryable flag. true (KYC-queuing, rate-limit) → back off and retry; false (moderation, copyright, quota) → change content / swap image, retrying will never work.一锤定音的信号:retryable 字段。true(KYC 排队、限流)→ 退避后重试;false(审核、版权、配额)→ 改内容/换图,重试永远无效。

Billing — 402 vs 403计费 —— 402 与 403

• 402 insufficient_credits (with needed) — this call costs more than the balance. Tell the user to recharge; do not loop-retry.(带 needed)—— 本次点数不够。提示用户充值;绝不循环重试。
• 403 not_entitled (reason: no_credits / status_suspended) — zero balance or suspended account, blocked at the gate before any spend.(reason:no_credits / status_suspended)—— 零余额或账户封禁,在扣费前被入口拦。
• Prepaid, no overdraft: post-paid text settling short drains the balance to zero and blocks the account until recharge — never a negative balance.先充值不欠费:后付文本结算不足会把余额扣尽到零并停用账户直到充值 —— 绝不出现负余额。

Vendor / edit 400 / auth / async厂商 / 区间替换 400 / 鉴权 / 异步

• Segment replace: start_sec/end_sec must be non-negative integers, start < end, within the source duration; source must be ≥ the vendor minimum. VIDEO_EDIT_MODE off → 403.区间替换:start_sec/end_sec 须非负整数、start < end、不超源片时长;源片须 ≥ 厂商下限。编辑模式未开 → 403。
• Vendor: timeout → 504, unreachable → 502. Rate-limited → 429 with Retry-After.厂商:超时 → 504,不可达 → 502。限流 → 429 带 Retry-After。
• Auth: invalid api key 401 → create a new key (the MCP client auto-re-exchanges the token once). scope insufficient 403 → use a key with produce / read scope.鉴权:invalid api key 401 → 重建 Key(MCP 客户端会自动重换一次令牌)。scope 不足 403 → 换带 produce / read scope 的 Key。
• Async: long steps return status:generating immediately — poll get_storyboards / get_jobs / get_pipeline_status; stable counts = done; stuck → read get_jobs errorMsg. Gateway hard timeout 180s → 504.异步:长步骤立即返 status:generating —— 轮询 get_storyboards / get_jobs / get_pipeline_status;数量稳定=完成;卡住→读 get_jobs 的 errorMsg。网关硬超时 180s → 504。

Facade 4xx you'll hit most (order matters)最常撞的门面 4xx(顺序很重要)

• Follow the order: set_script (raw) → rewrite_script → extract_assets → storyboards → frames → videos. Skipping gives "先 set_script / 本集无剧本 / 本剧尚无角色".照顺序走:set_script(原始)→ rewrite_script → extract_assets → 分镜 → 帧 → 视频。跳步会得到「先 set_script / 本集无剧本 / 本剧尚无角色」。
• "本集 N 镜均无首帧;先 generate_frames，否则视频会退化成无锚点 t2v" — always generate frames before videos.「本集 N 镜均无首帧;先 generate_frames…」—— 出视频前必先出帧,否则退化成无锚点 t2v(白花钱)。
• invalid or expired quote_id — a quote_id is one-time and expires in 15 min. Re-call the matching */quote for a fresh one.invalid or expired quote_id —— quote_id 一次性、15 分钟过期。重调对应 */quote 拿新的。
• 404 not found on someone else's resource is intentional (cross-tenant probes 404, never leak existence).别人的资源 404 是故意的(跨租户探测一律 404,不泄漏资源是否存在)。

Agent handling principlesAI agent 通用处理原则

• Three action classes: moderation / identity / copyright rejection → change content or swap image (retry never works); vendor overdue / token → not self-healable (tell user / wait); network / timeout / BestOfN transient → retry.三类动作:审核/身份/版权拒 → 改内容或换图(重试无效);厂商欠费/token → 不可自愈(提示用户/等待);网络/超时/BestOfN 偶发 → 可重试。
• 402 = stop and prompt to recharge; never loop-retry. Failed spends are already refunded.402 = 停并提示充值;绝不循环重试。失败扣费已自动退款。
• Poll, don't block. Read the message/errorMsg to decide the action — it's the authoritative "what to do".轮询,别阻塞。读 message/errorMsg 决定动作 —— 它就是权威的"该怎么办"。

Status codes状态码

Security安全

• Keys are stored hashed — a lost plaintext can't be recovered, so rotate (revoke + create).Key 只存哈希 — 丢失明文无法找回,丢了就吊销重发。
• Each key is independently revocable and audited (last-used time visible in Settings).每把 Key 独立吊销、独立审计(设置页可见最近使用)。
• Tokens expire in 15 minutes; revoking a key never affects your web login.令牌 15 分钟过期;吊销 Key 不影响网页登录。
• Keep keys in environment variables or a secrets manager — never commit them.Key 放环境变量或密钥管理,别提交进仓库。