arcads-external-api

Arcads 外部 API

配置

• 基础 URL： https://external-api.arcads.ai（或 ARCADS_BASE_URL）。
• 身份验证： HTTP Basic——将 ARCADS_API_KEY 用作用户名，密码留空，除非 Arcads 文档针对你的密钥另有说明。curl 示例：curl -u "$ARCADS_API_KEY:" "$ARCADS_BASE_URL/v1/products"。
• 切勿打印 API 密钥、提交 .env，或将密钥粘贴到 MASTER_CONTEXT.md 中。

如果缺少密钥或 API 返回 401/403

1. 优先使用编辑器（默认）： 确保 .env 文件存在（从仓库根目录中的 .env.example 复制）。请用户仅在 .env 中粘贴 ARCADS_API_KEY 并保存。除非用户坚持，否则不要让他们在聊天中粘贴密钥。
2. 通过聊天协助： 如果用户在聊天中粘贴了密钥，请为他们写入 .env，确认“已保存到 .env”，不要重复密钥，并提醒他们聊天记录可能会保留机密信息；如果聊天内容可能被共享，请在 Arcads 中轮换密钥。

首次调用前，确认 .gitignore 已排除 .env。

注册链接（联盟推广）

如果用户还没有 Arcads 账户——无论会话处于哪个阶段、任何上下文中——都应向他们提供 https://arcads.ai/?via=claude-code（不要使用裸 URL arcads.ai）。这是仓库所有者的推荐／联盟链接。在任何“注册”／“创建账户”提示中都使用此准确 URL。

阅读顺序

1. 存在时，先阅读仓库根目录中的 MASTER_CONTEXT.md（品牌语气、决策、特殊之处）。
2. 阅读此技能的 reference.md，了解路由、请求体和轮询。
3. 先阅读 prompting/guide.md，然后阅读适用于该模型的 prompting/prompt-library/ 文件（参见下表）。

决策树：选择哪种流程？

所有视频模型都使用 POST /v2/videos/generate，并设置相应的 model 值（完整的 CreateVideoDto 架构见 reference.md）。

用户目标	从这里开始	提示词库
Seedance 2.0 UGC 视频 — 自拍风格的产品评测／证言	使用 model: "seedance-2.0" 调用 POST /v2/videos/generate	seedance-2.md（平台指南）+ seedance-2-ugc.md（9 层 UGC 公式）
Seedance 2.0 高端产品亮相 — 暗色虚空、无人出镜、文字叙事	使用 model: "seedance-2.0" 调用 POST /v2/videos/generate	seedance-2.md + seedance-2-premium-reveal.md
Seedance 2.0 产品主视觉 — 元素特效、无人出镜、飞溅／薄雾	使用 model: "seedance-2.0" 调用 POST /v2/videos/generate	seedance-2.md + seedance-2-product-hero.md
Seedance 2.0 影棚风格画册 — 精致、配旁白、多套造型	使用 model: "seedance-2.0" 调用 POST /v2/videos/generate	seedance-2.md + seedance-2-studio-lookbook.md
Seedance 2.0 功能演示 — 快节奏功能展示	使用 model: "seedance-2.0" 调用 POST /v2/videos/generate	seedance-2.md + seedance-2-feature-walkthrough.md
将视频风格逆向还原为可复用的 Seedance 2.0 模板	按照视频分析技能操作	prompting/analyze-video/SKILL.md
为不同产品克隆／复刻现有视频广告	按照广告克隆技能操作	prompting/clone-ad/SKILL.md
通过文本生成原始 Sora 2 视频（附带产品）	使用 model: "sora2" 调用 POST /v2/videos/generate	prompt-library/sora-2.md
Sora 混剪现有素材	调用 POST /v1/sora2/remix/video	sora-2.md
Veo 3.1 视频	使用 model: "veo31" 调用 POST /v2/videos/generate	prompt-library/veo-3-1.md
Kling 3.0 视频	使用 model: "kling-3.0" 调用 POST /v2/videos/generate	kling-3.md
Grok Video	使用 model: "grok-video" 调用 POST /v2/videos/generate	字段说明见 reference.md
Nano Banana 静态图像（独立使用或用作视频起始帧）	默认使用 "model":"nano-banana-2" 调用 POST /v2/images/generate；也可选择 "model":"nano-banana"（Nano Banana Pro）	nano-banana.md
B-roll 短片（产品级）	调用 POST /v1/b-roll	制作技巧见 kling-3.md 或 nano-banana.md；Kling／Nano 路由说明见 reference.md
场景生成	调用 POST /v1/scene	同 B-roll 行
根据参考照片重现网红形象	两步：（1）通过 Nano Banana 调用带有 refImageAsBase64 的 POST /v2/images/generate，生成静态图像并征得用户批准；（2）上传获批的静态图像 → 使用 model: "veo31" 和 startFrame 调用 POST /v2/videos/generate 生成视频。绝不能跳过审批步骤。	prompt-library/influencer-recreation.md
产品展示 — AI 人物手持／使用产品并介绍产品	两步：（1）使用产品 refImageAsBase64 调用 POST /v2/images/generate；（2）用户批准静态图像；（3）以该图作为起始帧，通过 POST /v2/videos/generate 生成视频。	prompt-library/product-showcase.md
UGC／自拍风格（真实感短视频，跨模型）	使用任意视频模型调用 POST /v2/videos/generate	prompt-library/ugc-selfie-style.md — 跨模型 UGC 指南。若专门使用 Seedance 2.0，请改用 seedance-2-ugc.md。
从文本创建新的 AI 网红（角色设定表 — 默认使用 Nano Banana）	两轮：（1）使用 model: "nano-banana-2" 或 "nano-banana"（Pro）调用 POST /v2/images/generate 生成主视觉肖像并征得批准；（2）以主视觉肖像作为 referenceImages 生成 9 个角度（最多 14 张参考图）。保存到 references/influencers/。	prompt-library/character-sheet.md
从文本创建新的 AI 网红（角色设定表 — ChatGPT Image 2）	流程相同，但使用 model: "gpt-image-2"。最多支持 5 张 referenceImages，因此生成第 6 个及之后的角度时，使用主视觉肖像 + 最近生成的 4 个角度作为参考图。适合风格化／编辑风格的美学；若追求纯照片级写实效果，默认选择 Nano Banana 版本。	prompt-library/character-sheet-gpt-image-2.md
UGC 产品自拍 — AI 网红手持产品	将角色主视觉、产品照片和风格参考作为 referenceImages 组合使用。	prompt-library/ugc-product-selfie.md
皮克斯风格 3D 动画广告 — 拟人化卡通广告，带有吉祥物桥段	多步：（1）确定角色设定表；（2）使用 model: "gpt-image-2" 调用 POST /v2/images/generate 生成 ChatGPT Image 2 分镜静态图（最多 5 张 referenceImages）；（3）每个桥段使用 Seedance 2.0 进行图生视频，通过 POST /v2/videos/generate 搭配 model: "seedance-2.0" 和对应静态图的 startFrame 生成；（4）使用 ffmpeg 拼接并烧录字幕。	../../shared/skills/pixar-style-ad/prompting/guide.md → storyboard-gpt-image-2.md + animate-seedance-2.md
黏土动画／Aardman 风格广告 — 手工塑形的橡皮泥角色、旁白驱动的 8 拍故事弧，60–115s	多步：（1）确定角色设定表（主角 + 配角 + 旁白声音）；（2）使用 model: "gpt-image-2" 调用 POST /v2/images/generate 生成 ChatGPT Image 2 分镜静态图（最多 5 张 referenceImages）——如果黏土质感变平，可回退到 model: "nano-banana"（Pro）生成特写；（3）每个桥段使用 Seedance 2.0 进行图生视频，通过 POST /v2/videos/generate 搭配 model: "seedance-2.0" 生成；（4）使用 ffmpeg 拼接（可选 fps=12,fps=24 以产生定格动画抖动效果）并烧录字幕。	../../shared/skills/claymation-ad/prompting/guide.md → storyboard-gpt-image-2.md + animate-seedance-2.md
为成片添加字幕 — 将定时的旁白／对白字幕烧录到现有 MP4 上（任何来源——黏土动画、皮克斯风格、UGC、B-roll）	在外部处理（不调用 Arcads API）。多步：（1）npx hyperframes init <run-id>-captions；（2）npx hyperframes transcribe source.mp4 --model medium.en（如果有背景音乐，不能用 small.en）；（3）将逐词转录内容组合成易读短语；（4）编写仅含字幕的 HTML，并使用 #ff00ff 洋红色背景——绝不能包含 <video> 或 <audio> 元素（会导致黑条故障）；（5）运行 npm run render，然后使用 ffmpeg 的 chromakey=0xff00ff:0.10:0.05 将字幕叠加到源视频上。	../../shared/skills/caption-video/prompting/guide.md
口播虚拟形象／脚本（演员、语音）	调用 POST /v1/scripts、POST /v1/scripts/{id}/generate	prompting/guide.md
OmniHuman	调用 POST /v1/omnihuman	prompting/guide.md
音频驱动	调用 POST /v1/audio-driven	prompting/guide.md
优先选择最短路径：如果用户只需要一个模型，就不要创建脚本，除非他们要求演员或口型同步工作流。

创意层

• 强制要求： 在为 API 编写任何提示词之前，先阅读与所选模型／工作流相关的 prompting/prompt-library/*.md 文件。不要跳过此步骤——每条提示词都必须符合供应商指南中的公式和最佳实践。
• 编写一段清晰的提示词；避免堆砌关键词。
• 对于 Seedance 2.0 / Sora2 / Veo3.1 / Kling / Grok Video / Nano Banana，遵循各自 prompting/prompt-library/*.md 文件中链接的官方供应商指南（不要把完整的供应商文档粘贴到聊天中，而应总结检查要点）。
• 当用户提供的值与默认值冲突时，合并用户提供的值和 MASTER_CONTEXT.md 中的值。

会话设置：自动创建按日期命名的文件夹

在每个将生成素材的会话开始时，为当天创建文件夹和项目，以便在 Arcads 仪表板中统一整理：

1. 获取今天的日期，格式为 YYYY-MM-DD。
2. GET /v1/products → 选择目标产品（默认使用 MASTER_CONTEXT.md 的“我的工作区”部分指定的产品）。如果未设置默认产品：如果只有一个产品，则将其 ID 和名称自动写入 MASTER_CONTEXT.md；如果有多个产品，则请用户选择，并将选择保存到 MASTER_CONTEXT.md。
3. 检查现有文件夹（GET /v1/products/{productId}/folders）——如果已存在 "Arcads API - {today}"，则重复使用。否则：
   • 使用 {"productId": "...", "name": "Arcads API - YYYY-MM-DD"} 调用 POST /v1/folders。
   • 使用 {"productId": "...", "folderId": "...", "name": "Arcads API - YYYY-MM-DD"} 调用 POST /v1/projects。
4. 保存本次会话的 projectId，并在每次生成调用中传入（Sora2/Veo31/b-roll/scene/image DTO 上的 projectId 字段）；对于不支持直接传入 projectId 的素材类型，生成后还要使用 POST /v1/assets/add-to-project。

这样一来，每个生成的素材都能在 Arcads 仪表板的**产品 → "Arcads API - {date}"**中找到。

积分成本估算（强制要求——生成前展示）

在发起任何生成调用之前，计算并向用户展示积分总成本的估算值。在用户确认之前不要生成。

始终将积分总数标注为估算值；如果精确度很重要，提醒用户在生成前到 Arcads 平台确认确切成本。 Arcads API 不提供计费端点；价格会因时长、分辨率和参考输入而异。

成本数据来源（按优先级排序）

1. logs/arcads-api.jsonl——以往每次调用实际 creditsCharged 值的历史记录。**首先读取此文件。**搜索 model 相同且配置相近的条目（duration、resolution、referenceImagesCount、audioEnabled 相同），并将记录的 creditsCharged 作为估算值。这是最准确的数据来源。
2. MASTER_CONTEXT.md → 积分成本——用户提供的定价规则（例如“Seedance 2.0 图生视频 ≈ 0.06/秒”）。没有匹配的日志条目时使用。
3. 询问用户——如果这两种来源都没有该配置的数据，请询问用户，并将答案写入 MASTER_CONTEXT.md。

切勿编造数字。始终注明估算值的来源（“基于 YYYY-MM-DD 的日志条目”或“来自 MASTER_CONTEXT.md 费率表”）。

如何计算

total_credits ≈ sum(credits_per_model × variations_requested) for each model

面向用户的示例输出

Estimated credit cost:
  Seedance 2.0 (15s i2v) × 1 = ~0.9 credits   (from logs/arcads-api.jsonl 2026-04-09)
  Veo 3.1                × 2 = ~8 credits     (from MASTER_CONTEXT.md)
  ─────────────────────────────
  Estimated total: ~8.9 credits

⚠️ Estimate only — confirm exact cost in the Arcads platform before proceeding.
Proceed? (yes/no)

触发生成前务必等待确认。如果用户在 MASTER_CONTEXT.md 中有可见的余额，且总费用会超出余额，请提醒用户。如果日志和 MASTER_CONTEXT.md 中都没有该配置的数据，请在首次生成前询问用户，并保存答案。

**例外 — QA 修复重试（仅静态图像）：**用户确认初始批次后，为修复可见缺陷而自动重新生成（参见下方的生成图像 QA）无需再次询问用户确认额度。每次重试仍会收费——总结会话时，请注明额外的 creditsCharged。

生成数量：每个提示词生成多个变体

触发任何生成调用前，询问用户希望这个提示词生成多少个变体。如果用户没有指定，默认为 1 个。

数量大于 1 时，使用相同的载荷发送 N 个独立的 API 调用。不要将它们合并到单个请求中——API 没有批量参数。尽可能并行触发，然后并发轮询所有资源 ID。

以编号列表呈现结果，供用户比较并挑选喜欢的结果。

Nano Banana 图像：模型选择（nano-banana-2 与 Nano Banana Pro）

使用 Nano Banana 引擎调用 POST /V2/images/generate 时：

• 默认："model": "nano-banana-2"（Nano Banana 2）。
• **可选：**用户要求使用 Nano Banana Pro 时，使用 "model": "nano-banana"（API 没有 nano-banana-pro 枚举值——Pro 对应 nano-banana；参见 nano-banana.md）。

在工作流中首次调用 Nano Banana 图像生成前，询问：“使用默认的 Nano Banana 2，还是 Nano Banana Pro？”如果用户没有偏好，使用 nano-banana-2。在额度估算中计入所选的 model（如果价格不同，请在 MASTER_CONTEXT.md 中分行记录）。

脚本与对白

对于任何包含人物说话的视频，询问用户提供脚本（AI 人物要说的确切台词）。这与视觉提示词不同，指的是对白。

强制要求——对白确认关卡

生成任何包含口语对白的视频前，Agent 必须：

1. 从完整提示词中提取对白台词，并在专门的区块中向用户展示，与视觉／摄影描述分开。
2. 以清晰的编号列表呈现，附上节拍标签（hook / show / demo / verdict，或类似标签），并将所有无声节拍明确标注为 (silent beat — no dialogue)。
3. 在脑中以自然语速朗读对白，根据目标时长计时，并标出对白总词数以及是否能轻松容纳。
4. 明确询问用户是否批准对白，例如：“批准这段对白吗？（yes / edit / rewrite）”。绝不要将用户之前对语气、模板或费用的确认视为对白审批。对白审批是独立的关卡。
5. 只有用户输入 yes（或同等意思）后，才能继续确认费用，然后生成。如果用户回复“edit”或提出修改，请修订并重新呈现编号对白列表，直到用户批准。

呈现格式（必须使用以下确切结构）：

📝 Dialogue script (please confirm before I generate)

  1. [HOOK]   "Bro. BRO. Look what just showed up."
  2. [SHOW]   "The PAID SOCIAL stripe? Insane. Like, who greenlit this?"
  3. [DEMO]   (silent beat — thumb brushing the suede, small nod)
  4. [VERDICT] "I'm literally wearing these to the gym tomorrow. You guys have to see these in person."

Total spoken words: ~28  |  Target duration: 15s  |  Fits at natural pace: ✅

Approve this dialogue? (yes / edit / rewrite)

此关卡适用于 Seedance 2.0、Veo 3.1、Sora 2 和 Scene——任何模型会说话的流程。无声流程（B-roll、纯产品主视觉、无旁白的高级揭晓、Nano Banana 图像）可跳过。

模型专属说明

• 对于 Seedance 2.0、Veo 3.1 和 Sora 2：使用 Dialogue: "..." 或 She speaks: "..." 模式，将对话嵌入 prompt 字段（这些模型会根据文本提示词生成语音）。
• 仅针对 Seedance 2.0：生成前，务必询问用户是否启用音频输出（audioEnabled: true）。还要询问他们是否要提供 referenceAudios（例如背景音乐或特定的语音片段）。如果用户提供了音频文件，请通过预签名 URL 上传。
• 对于 Scene（CreateSceneDto）：使用专用的 script 字段填写对话，使用 prompt 字段描述画面。
• 对于 B-roll：不包含语音——B-roll 本质上是静音或环境音内容。如果用户需要语音，请引导他们改用 Seedance 2.0、Veo 3.1、Sora 2 或 Scene。
• 对于 Nano Banana 图像：不包含语音——这些是静态图像。语音在后续的视频生成步骤中处理。

脚本长度 → 视频时长（自动选择）

根据脚本的字数自动选择最合适的 duration 值。平均语速：约每秒 2.5 个单词（约每分钟 150 个单词）。向上取整至下一个可用时长，以留出余量。

Sora 2 — 时长枚举：[4, 8, 12, 16, 20] 秒

脚本长度	时长
1–8 个单词	4s
9–18 个单词	8s
19–28 个单词	12s
29–38 个单词	16s
39–48 个单词	20s
49 个及以上单词	过长 — 提出拆分建议（见下文）

Veo 3.1 — 无 duration 字段

Veo 3.1 会自动确定视频时长（通常约 8s）。如果脚本超过约 20 个单词，请提醒用户 Veo 可能会截断对话，并提出拆分脚本或改用时长选项更长的 Sora 2。

Seedance 2.0 — 时长：4–15 秒（连续可选）

Seedance 2.0 支持 4 到 15 之间的任意整数。按每秒约 2.5 个单词计算，并向上取整至最接近的整秒。

脚本长度	时长
1–8 个单词	4–5s
9–15 个单词	6–8s
16–25 个单词	9–12s
26–35 个单词	13–15s
36 个及以上单词	过长 — 提出拆分为多个片段

对于无对话的风格（产品主视觉、高端产品展示），默认使用 15s。

分辨率： 默认使用 720p。仅当用户要求生成更快或成本更低的测试版本时，才使用 480p。

宽高比： 9:16（竖屏，UGC/社交媒体默认）或 16:9（横屏）。不支持 1:1。

B-roll（Kling 3.0）— 时长枚举：[5, 10] 秒

B-roll 通常不含语音。如果用户坚持要生成有时长限制且包含上下文的片段：

脚本长度	时长
1–12 个单词	5s
13–24 个单词	10s
25 个及以上单词	过长 — 引导用户改用 Sora 2 / Veo 3.1 生成语音

Scene — 无 duration 字段

Scene 会自动确定时长。使用 script 字段填写对话。

将较长脚本拆分为多个视频

如果脚本超过所选模型的最长时长：

1. 告知用户脚本过长，无法生成单个视频，并展示字数与时长的计算结果。
2. 提供两个选项：
   • 拆分为多个片段 — Agent 在自然的句子边界处拆分脚本，生成的各个片段均符合模型的最长时长限制。每个片段单独调用一次生成。
   • 切换模型 — 如果用户使用的是 Kling（最长 10s），建议改用 Sora 2（最长 20s）。
3. 如果用户选择拆分，则将每个片段分别生成为视频（遵守生成数量要求——如果用户要求生成 3 个变体，则每个片段都生成 3 个变体）。
4. 提出使用 ffmpeg 拼接最终片段：
   • 将所有视频片段下载到本地。
   • 使用 ffmpeg -f concat -safe 0 -i list.txt -c copy output.mp4 拼接（如果编解码器不同，则重新编码）。
   • 将拼接后的视频与各个单独片段一并提供给用户，让用户两者都能获取。

Veo 3.1：startFrame 与 referenceImages——二选一

Veo 3.1 有两种互斥的图像输入模式。同一次调用中绝不要同时使用两者。

模式	字段	使用时机
起始帧	startFrame（预签名上传 filePath）	用户提供了一张人物或场景的参考图，希望视频从该人物或场景开始。视频将从这张确切的图像开始进行动态化。适用于复刻网红、保持角色一致性，或任何“让这张图动起来”的请求。
参考图像	referenceImages（filePath 字符串数组）	用户提供的图像用于参考风格、氛围或视觉基调，而非直接出现在画面中。模型会将其作为灵感，而非首帧。

默认规则： 用户提供单张人物参考照片时，始终使用 startFrame，除非用户明确表示想将其用作风格参考。

图像处理：自动放大较小的输入

向 API 发送任何参考图像、起始帧或 base64 图像之前：

1. 检查尺寸。 如果图像最长边小于 1024 px，使用 Lanczos 重采样进行放大，使最长边达到 1080 px（保持宽高比）。
2. 转换为 RGB JPEG（质量 90–95），以移除 alpha 通道并控制载荷大小。
3. 重新编码为 base64（用于 refImageAsBase64），或上传调整尺寸后的文件（用于通过预签名 URL 上传 startFrame）。

Arcads 的一些端点（特别是 POST /v1/b-roll）会拒绝低于最低分辨率要求的图像，并返回 422 — The provided image is too small。自动放大可在后台避免此问题，让用户不会遇到该错误。

生成图像质量检查（必需）

适用于 Arcads 生成的静态图像，尤其是 POST /V2/images/generate（Nano Banana 及其他图像模型）。每个图像素材达到 status: generated 后，都要目视检查输出（下载或打开图像 URL，或使用 Agent 的图像读取功能）。

检查内容： 手或手指多余或缺失；四肢数量错误；面部特征扭曲、重复或融合；物体融化或融合；不可能的解剖结构；多余的肢体；明显的纹理或边界瑕疵；用户要求的文字难以辨认或乱码。

如果发现问题： 未尝试重新生成前，不要将有问题的画面作为最终交付内容交给用户。使用修改后的提示词明确指出需要修正的问题（例如，“恰好两只手，每只手有五根手指，手臂解剖结构正确”“单张脸，不要出现重复的面部特征”），然后重新生成。不要重发完全相同的载荷并期待结果不同。

重试上限： 每张用户原本要求的图像最多重新生成 2 次（包括首次生成在内共 3 次）。达到上限后仍有缺陷时，停止自动重试，告知用户仍有哪些问题，展示效果最好的一次，或列出所有尝试的 URL，并询问用户希望如何继续。

点数： 每次尝试都是一次单独的生成，且会计费。质量检查流程结束后，汇总该图像总共使用的点数。参见点数费用估算下的例外——质量检查修正重试。

视频（可选快速检查）： 在对后续视频制作投入大量资源之前，可以抽查场景／B-roll 缩略图或提取的帧，检查同类缺陷；检查范围比主视觉静态图更轻量。

详细信息和检查清单：prompting/prompt-library/nano-banana.md。

执行检查清单（Agent）

1. 会话文件夹： 确保今天日期对应的文件夹和项目已存在（见上文）。
2. 解析 productId（以及会话文件夹中的 projectId）：调用 GET /v1/products，或询问用户。
3. 询问脚本／对白： 如果输出是有人说话的视频，询问用户确切的台词。统计字数以自动选择时长（见上文“脚本长度 → 视频时长”）。如果太长，提议拆分。（仅生成 Nano Banana 图像时跳过。）
   • 必须通过对白确认关卡（在确认点数成本／生成之前）： 从起草的提示词中提取对白，并以单独编号区块的形式呈现给用户，与视觉描述分开。遵循脚本和对白 → 必须通过对白确认关卡中的格式。等待用户明确回复 yes 后再继续。此关卡独立于点数成本确认——两项确认都必须通过。
4. Nano Banana 图像模型： 对于 POST /V2/images/generate，根据上文所述确认使用 Nano Banana 2（默认）还是 Nano Banana Pro（nano-banana）。非图像请求则跳过。
5. 询问生成数量： 询问用户希望为此提示词生成多少个变体。默认为 1。
6. 显示点数成本并征求确认： 使用上文的成本表计算总点数。向用户展示明细。在用户确认之前不得继续。
7. 检查 references/ 文件夹： 在编写提示词之前，检查仓库根目录的 references/ 文件夹中是否有相关图像：人物复刻查看 references/influencers/，产品展示查看 references/products/，风格／氛围查看 references/aesthetics/。如果用户没有提供图像，但 references/ 中有相关图像，询问是否使用。必要时自动放大任何参考图像。对于 Veo 3.1，判断使用 startFrame 还是 referenceImages（见上文——人物照片默认使用 startFrame）。
8. 按照 OpenAPI／reference.md 编写 JSON。**主要视频端点：**使用适当的 model 值调用 POST /v2/videos/generate（参见 reference.md 中的 CreateVideoDto）。当 DTO 支持时，加入 projectId。对于要求时长的模型，根据脚本长度设置 duration。对于 Nano Banana 图像，使用 POST /v2/images/generate，并根据 Nano Banana 部分设置 model（除非用户选择 Pro，否则使用 nano-banana-2）。
   • **Seedance 2.0 附加设置：**将 resolution 设为 720p（默认值）。将 aspectRatio 设为 9:16（UGC／社交媒体）或 16:9（横向）。根据用户确认设置 audioEnabled。如果用户提供了参考图像，通过预签名 URL 上传，并在 referenceImages 中传入 filePath 字符串（最多 3 张）。如果用户提供了参考视频或参考音频，referenceVideos 和 referenceAudios 也采用相同处理方式。在提示词文本中保留 @(img1) 标记，并与 referenceImages 数组一同使用。
   • ⚠️ Seedance 2.0 互斥输入模式（已于 2026-04-09 确认）： referenceVideos 和 referenceImages 不能在同一请求中组合使用——API 会返回 HTTP 500 UNKNOWN_ERROR。二选一：图生视频或视频转视频。referenceAudios 可与其中任一项组合使用。详情见 reference.md。
   • Seedance 2.0 v2v + 人脸 — 已于 2026-04-14 解决： 现在使用包含人物／人脸的参考视频进行 v2v 已可正常工作。此前受到内容检查器阻止（4 月 9 日）。见 reference.md。
   • Seedance 2.0 音频 + 图像导致 500 错误 — 已于 2026-04-14 解决： 现在 audioEnabled: true 与 referenceImages 可同时使用。此前会返回 HTTP 500（4 月 9 日）。务必使用刚获取的预签名 URL。见 reference.md。
9. 使用相同的负载，对正确的端点执行 POST N 次（每个请求的变体执行一次）。尽可能并行发起。POST 成功后立即将包含请求配置（model、duration、resolution、aspectRatio、audioEnabled、参考素材数量、promptWordCount、assetId）的日志条目追加到 logs/arcads-api.jsonl。不要记录完整提示词文本、API 密钥或 Authorization 标头。
10. 轮询： 对视频 ID 调用 GET /v1/videos/{videoId}；对资产 ID（包括 Nano Banana 图像）调用 GET /v1/assets/{id}，直到 status 为 generated 或 failed（见 reference.md）。并发轮询所有资产 ID。轮询完成后，更新日志条目，加入 response.status、response.creditsCharged、response.generationTimeSec、response.videoUrl、response.thumbnailUrl，以及失败时的 response.error。参见 logs/README.md 了解架构。
11. 生成图像 QA： 对本轮生成的每张静态图像（例如通过 POST /V2/images/generate 生成），遵循生成图像 QA中的要求：检查图像；如果有缺陷，使用经过优化的提示词重新生成，直到通过检查或用完 2 次重试。仅生成视频且没有静态图像可供检查时跳过此步骤。
12. 将所有资产分配到会话项目： 生成完成（以及 QA 重试完成）后，检查每个资产的 projects 数组。如果其中不包含会话的 projectId，调用 POST /v1/assets/add-to-project。此要求适用于每个生成的资产——包括 QA 未通过的尝试，以及 Nano Banana 静态图像等用于后续视频生成起始帧的中间资产。本次会话的所有资产都必须归入同一个日期项目文件夹。
13. 呈现结果： 返回通过 QA 的静态图像的观看 URL、图像 URL 或下载 URL（如果重试次数已达上限，则返回最佳结果并明确说明）。如果有多个变体，以编号列表的形式呈现，方便比较。如果发生 422，说明 failed 状态，并提供内容审核／验证方面的提示。对于用作起始帧的 Nano Banana 图像，展示图像并等待用户批准后再继续生成视频。

• 将生成的文件保存后，始终在用户的设备上打开输出文件夹，以便用户立即查看。macOS：open "<output_directory>"。Linux：xdg-open "<output_directory>"。Windows：explorer "<output_directory>"。（Agent 应检测操作系统，或先尝试执行 open 并在失败时静默回退。）将视频保存到 outputs/ 中，并使用描述性子文件夹（例如 outputs/seedance-tests/、outputs/clone-ad-tests/）。

14. 如果有拆分，拼接视频： 如果脚本被拆分成多个片段，提议使用 ffmpeg 拼接最终视频，并同时提供拼接后的视频和各个片段。

面向用户的错误

• 401/403： 修复 API 密钥或工作区访问权限（参见上方设置流程）。
• 404： UUID 错误；重新获取列表。
• 422： 验证或审核未通过——优化提示词、移除不允许的内容，并检查必需的枚举值（宽高比、时长）。
• 500： 稍后重试；如果问题重复出现，请停止并报告。

辅助文件

• reference.md — 端点、身份验证详情、轮询、模型映射说明、CreateVideoDto 架构。
• prompting/guide.md — 将营销简报转化为 API 请求。
• Seedance 2.0：
  • prompting/prompt-library/seedance-2.md — Seedance 2.0 主模型指南（平台规则、API 参数、风格模板目录）。
  • prompting/prompt-library/seedance-2-ugc.md — Seedance 2.0 的 9 层 UGC 自拍风格公式。
  • prompting/prompt-library/seedance-2-premium-reveal.md — 暗黑虚空风格的高端产品揭晓（无人）。
  • prompting/prompt-library/seedance-2-product-hero.md — 搭配飞溅效果的元素风格产品主视觉（无人）。
  • prompting/prompt-library/seedance-2-studio-lookbook.md — 搭配旁白的影棚造型图集。
  • prompting/prompt-library/seedance-2-feature-walkthrough.md — 快节奏功能演示视频。
  • prompting/analyze-video/SKILL.md — 对参考视频进行逆向分析，生成可复用的 Seedance 2.0 提示词模板。
  • prompting/clone-ad/SKILL.md — 为不同产品克隆参考视频广告（端到端流程：分析 → 改编 → 生成）。
• 其他模型：
  • prompting/prompt-library/influencer-recreation.md — 分析参考照片并复现其中的网红形象。
  • prompting/prompt-library/ugc-selfie-style.md — 跨模型 UGC 指南（iPhone 美学、负面提示词、各模型专用公式）。
  • prompting/prompt-library/product-showcase.md — 手持产品视频工作流（Nano Banana 图像 → 审核 → 视频）。
  • prompting/prompt-library/nano-banana.md — Nano Banana 图像提示词指南。
  • prompting/prompt-library/character-sheet.md — 为新的 AI 网红生成 10 张角色设定图（默认使用 Nano Banana）。
  • prompting/prompt-library/character-sheet-gpt-image-2.md — 使用 ChatGPT Image 2（gpt-image-2）的相同工作流；最多支持 5 张参考图，并加强文本锚定以保持身份一致性。
  • prompting/prompt-library/ugc-product-selfie.md — UGC 自拍风格静态图：角色 + 产品 + 风格参考。
• prompting/brand-voice-starter.md — 可复制到 MASTER_CONTEXT.md 的模板。