MUSE AV

模板字段标准 ​

建模板之前先看这页。服务端按这套契约校验 —— 比如 prompt_template 里有占位符却没声明 fields，会在建的时候就被挡下来， 而不是等到调用时才发现模板是坏的。

两种生成模式 ​

三类模板（图片 / 文案 / 视频）都支持这两种：

模式怎么写什么时候用
form（表单填空）prompt_template 里放 {key} 占位符 + fields 声明字段，用户填表，服务端做确定性替换首选。 不用指望调用方写得出好提示词，而且这一步不花模型钱
spec（规范展开）skill_spec_md 给整篇规范，交给模型按用户一句话描述展开字段太多、太开放，列不出表单时才用

漏填必填项一律 400

占位符原样进提示词会直接产出废图、废文案。挡在前面比让你白花一次钱好。

fields 每一项 ​

字段说明
key替换 prompt_template 里 {key} 的变量名
label表单上显示的名字
type可选，text / textarea / select，默认 text
placeholder可选，示例值
help可选，字段下方的说明
required可选，默认 true；false = 选填
optionsselect 类型必填：非空数组，元素为 "value|label" 字符串（租户 UI 的存法）或 {label, value} 对象

本表由中台 /api/doc-contracts 在文档构建时下发，真源 shared/template-contract.js—— 不是手抄的，中台改了下次构建自动跟上。

type 的合法取值也在上表的说明里。select 类型必须给 options， 否则渲染出来是个空下拉，等于没这个字段。

三类模板的契约 ​

图片模板type=image

  • 存在表 templates
  • 列表接口 GET /api/templates?type=image
  • 怎么生成 POST /api/generate { skill_slug | template_id, input }
  • 建的时候必须给 zh_name
核心字段（表上的列）说明
slug对外调用标识（skill_slug）。没有 slug 的模板不会出现在技能列表、也接不了流水线钩子
ratio画幅，如 3:4 / 9:16。图片任意模型都能大致适配任意画幅，所以放核心层
sample_images样图数组，列表缩略图取第一张
category分类
domain领域
description一句话说明
generation_configs 每项说明
model模型名，auto = 走中台路由表
prompt_templateform 模式：含 {key} 占位符的提示词
fieldsform 模式：表单字段声明，见 FIELD_SPEC
skill_spec_mdspec 模式：整篇规范正文（不下发给租户）
ref_required是否必须带参考图
default_reference_images模板自带参考图（URL 数组）。调用方没传参考图时回落到它；调用方传了以调用方为准
qualitylow/medium/high，仅部分上游支持

文案模板type=article

  • 存在表 templates（同图片表，靠 template_type=article 区分）
  • 列表接口 GET /api/templates?type=article
  • 怎么生成 POST /api/article { template_slug, input }
  • 建的时候必须给 zh_name
核心字段（表上的列）说明
slug对外调用标识（article 接口用 template_slug 取它）
category分类
description一句话说明
generation_configs 每项说明
format输出格式，决定返回哪些字段：xiaohongshu / wechat / detail / script
prompt_templateform 模式：含 {key} 占位符的提示词
fieldsform 模式：表单字段声明
skill_spec_mdspec 模式：整篇写作规范

视频模板type=video

  • 存在表 video_templates（独立表）
  • 列表接口 GET /api/video-templates
  • 怎么生成 POST /api/videos { template_id, input }
  • 建的时候必须给 zh_nameslug
核心字段（表上的列）说明
zh_name模板名（列表和选择器上显示的）
slug对外调用标识
sample_cover_image列表缩略图（视频本身不适合当缩略图）
sample_video_url示例视频
category分类
description一句话说明
generation_configs 每项说明
model视频档次：'auto'（交给路由决定）或当前上游支持的渠道代号之一（artsdance-2-0-pro-260801=Seedance 2.0、artsdance-2-0-fast-260801=Seedance 2.0 Fast、artsdance-2-0-mini-260801=Seedance 2.0 Mini、artsdance-2-5-pro-260801=Seedance 2.5）。不能写别的字符串——上游不认的名字会在生成时才炸
ratio画幅——放配置里而非核心层：换模型/换上游，支持的画幅可能整个变
duration时长（秒），同理放配置里
prompt_templateform 模式：含 {key} 占位符的提示词
fieldsform 模式：表单字段声明
skill_spec_mdspec 模式：整篇规范

本表由中台 /api/doc-contracts 在文档构建时下发，真源 shared/template-contract.js—— 不是手抄的，中台改了下次构建自动跟上。

变量白名单 ​

图片转模板只允许产出下面这些占位符，白名单外的一律丢弃。

占位符表单上显示指什么
{title}主标题主标题
{subtitle}副标题副标题 / 主题行
{subject}画面主体画面主体（人物 / 产品 / 角色）——可能来自文字，也可能来自画面
{date}日期日期 / 时间
{location}地点地点 / 城市 / 场馆
{watermark}水印水印 / 署名 / logo 文字
{body}正文正文 / 说明文案
{cta}行动号召行动号召（购票、下单等按钮文字）
{style}风格色调风格（非文字，从画面提取）

本表由中台 /api/doc-contracts 在文档构建时下发，真源 shared/template-contract.js—— 不是手抄的，中台改了下次构建自动跟上。

为什么是「通用语义」而不是你的业务词

中台是多租户公共层。把 {artist} / {city} 这种某一家的业务叫法写进公共模板， 别的租户拿到就是垃圾。

所以变量按元素在画面里扮演的角色命名。 你自己的叫法通过 variable_labels 映射到表单显示名，key 永远是通用名。

做猫砂包装图时 {title} 是产品卖点、{subject} 是包装袋； 做演出海报时 {title} 是演出主题、{subject} 是艺人。 key 不变，展示成什么名字由你决定。

同一角色出现多处 ​

一张海报上「正中」和「右中」是两处不同的副标题怎么办？

第 1 处仍然写 {subtitle}，第 n 处（n≥2）写 {subtitle_2} / {subtitle_3}。 语义与基名完全相同，白名单校验按基名判定。

为什么不把 subtitle_2 也加进白名单

那是枚举爆炸 —— 九个角色乘以若干槽位，白名单会变成一张表， 而它的价值恰恰是「短，且都是语义」。

槽位号不是语义，是「这张图上恰好有几处」，属于逆向观察到的事实，不属于公共契约。

视频模板的 model 有额外校验 ​

model 只能是 auto 或真实存在的档次之一。

而且锁死档次之后，resolution 和 duration 得配得上它 —— 2.0 pro 只收 480p，2.5 只收 720p/1080p；2.0 系列封顶 15 秒，2.5 到 30 秒。 配不上的组合在建模板时就会被拒。

想省心就写 auto，让系统按你要的分辨率和时长挑一档能满足的。

相关 ​