口播稿生成 API

把一篇文章改写成 30-45 秒竖屏口播稿：三段结构（钩子 + 正文 + 落点）、双钩子收尾，自带时长与字数门禁。

POST /v1/scripts/write v1 免费额度 · 申请制

快速开始

替换 YOUR_KEY 为你申请到的 Key，直接发起首个请求：

# 文章 → 口播稿（正文少于 200 字会直接拒绝）
curl -X POST https://skyaibi.com/v1/scripts/write \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "企业AI落地日报",
       "positioning": "把 AI 新进展翻译成企业能用上的话",
       "title": "…", "body": "正文全文（不少于 200 字）…",
       "angle": "从成本角度切入", "keep_tags": ["企业AI落地"]}'

# 响应
{"ok": true, "gate": "pass",
 "script": {"hook": "建模外包几千块一个，这笔钱可能要省了。",
            "body": "…", "outro": "…",
            "chars": 195, "estimated_seconds": 34.8,
            "hashtags": ["三维建模", "AI降本"],
            "cover_text": "建模外包钱要省了",
            "material_keywords": ["三维模型生成软件界面", "…"],
            "key_facts": ["…"]}}

示例参数为示意，正式字段与枚举值以 OpenAPI 3.1 规范为准（下方可下载，可直接导入 Apifox / Postman）。

鉴权与调用约束

正文不足 200 字直接返回 422：这是刻意的门禁。正文太少时模型只能自己补，存在编造事实风险，宁可拒生成也不产出不可信内容
全文口径：hook ≤22 字（约前 3 秒）＋ body 120-160 字＋ outro ≤40 字，合计不超过 220 字；首次不达标会自动压缩返工一次，仍不达标则返回 gate 为 warn 并附具体问题
estimated_seconds 按 5.6 字/秒 成片有效语速换算，可直接作为配音时长预估
hashtags 已做合规过滤：自动移除公司名/品牌名标签并截断到 3 个（实测堆标签会被判定为营销号信号，压制推荐）
material_keywords 可直接用于素材库检索，key_facts 列出正文用到的关键事实与数字，便于人工核对
限频规则：免费额度内默认 10 次/分钟，超限返回 429

接口清单

方法	路径	说明
POST	/v1/scripts/write	文章 → 口播稿（含字数/时长门禁）
GET	/v1/scripts/style	获取成片结构口径与时长换算规则

错误码

code	含义	处理建议
40001	无效 API Key	检查 X-API-Key 是否正确、是否已开通
40002	免费额度用尽	升级套餐或联系商务扩容
422	参数缺失/不合法	按错误信息中 field 字段修正请求体
429	触发限频	降低调用频率，参考 Retry-After 响应头
500	服务内部错误	稍后重试，持续失败请联系我们
422	body_too_short	正文少于 200 字，拒绝生成以防编造事实

规范与申请

下载 OpenAPI 3.1 规范（JSON）申请 API Key

FAQ

常见问题

为什么正文不足 200 字就拒绝生成？

因为口播稿必须基于事实。实测中曾出现：同一条新闻有短讯源和全文源，选中短讯后模型只能靠标题发挥，生成了三百多字的口播稿，但原文正文是 0 字——一旦发布即构成编造。所以把正文长度设成硬门槛，从源头拦住这类风险。

30-45 秒这个口径是怎么来的？

来自实测数据：原来的 55-70 秒长稿，完播率只有个位数到十几个百分点，观众在前 5 秒就走完了；改成 30-45 秒并强化前 3 秒钩子后，完播率明显改善。口播稿的时长不是审美选择，是推荐算法的杠杆。

返回的 gate=warn 要处理吗？

建议处理。warn 表示自动返工后仍未完全达标（例如仍然超字），响应里的 gate_problems 会列出具体问题。可以直接拦截不发，也可以人工微调后再用——关键是别把 warn 当成 pass。