供应商与模型配置

ArcReel 把 Agent（智能体）、文本生成、图像生成、视频生成和 TTS 分成独立能力。你可以为不同项目和媒体类型选择不同供应商，而不必把整条生产链绑定到一家平台。

1. 先区分两类供应商

1.1 Agent 供应商

Agent 负责：

• 理解用户意图；
• 分析小说和剧本；
• 规划每集脚本时识别角色、场景和道具；
• 规划分集；
• 规范化剧本；
• 编排后续生成任务。

ArcReel 的 Agent Runtime 基于 Claude Agent SDK，支持 Anthropic 官方服务以及项目所支持的兼容配置。

Agent 供应商不一定承担实际图片和视频生成。

1.2 媒体与文本供应商

这些供应商负责：

• 结构化文本生成；
• 图片生成和编辑；
• 视频生成；
• TTS。

一个完整项目可以采用组合策略，例如：

• Agent：高质量推理模型；
• 文本结构化：速度更快的文本模型；
• 角色设计：高质量图像模型；
• 批量分镜：低成本图像模型；
• 样片视频：快速视频模型；
• 最终关键分镜：高质量视频模型；
• 旁白：独立 TTS 供应商。

2. 预置供应商能力矩阵

供应商的具体模型、参数、地区和价格会持续变化。下表只表达 ArcReel 的能力覆盖层级，实际可选项以设置页为准。

供应商	文本	图像	视频	TTS	典型用途
Gemini	✅	✅	✅	✅	多模态文本、参考图、视频生成和 TTS
火山方舟	✅	✅	✅	—	国内网络环境下的文本、图像和视频
火山方舟 Agent Plan	✅	✅	✅	✅	订阅套餐内的文本、图像、视频和 TTS
Grok	✅	✅	✅	✅	文本、图像、视频生成和 TTS
OpenAI	✅	✅	—	—	文本和图像
Vidu	—	✅	✅	—	图像、图生视频和参考生视频
阿里百炼	✅	✅	✅	✅	文本、图像、视频和旁白配音（TTS）
MiniMax	✅	✅	✅	✅	文本、图像、视频和 TTS
可灵 Kling	—	✅	✅	—	图像、图生视频和参考生视频
Agnes	✅	✅	✅	—	文本、图像和视频
自定义供应商	取决于接口	取决于接口	取决于接口	取决于接口	私有网关、本地模型或第三方兼容服务

内置 OpenAI 供应商提供文本和图像能力；OpenAI 兼容的视频与 TTS 通过自定义供应商的调用端点接入。

3. 配置层级

ArcReel 支持：

1. 全局默认供应商；
2. 项目级供应商覆盖；
3. 预置供应商内多个 API Key（自定义供应商每个配置使用一个 API Key）；
4. 不同媒体类型使用不同供应商。

优先级通常为：

项目级配置 > 全局默认配置

预置供应商在每种媒体类型下有一个推荐模型，由 ArcReel 官方维护，在供应商详情页的模型列表里标为「推荐」。推荐模型只是建议，生成时使用的始终是全局与项目设置里选中的模型。推荐模型只在以下时机起作用：

• 给预置供应商配置第一个 API Key 或凭证时，还没有设置全局默认模型的媒体类型设为这个供应商的推荐模型，已有的设置不变；
• 全局默认模型所在的预置供应商换了推荐模型，或者某种媒体类型还没有默认模型、已配置的预置供应商新给出了推荐模型时，「全局设置 → 默认模型」里对应的默认模型下方会提示。可以切换到推荐模型，也可以保留当前设置；处理后，这个供应商这种媒体类型的推荐模型再次变化前不再提示。删除 API Key 后重新配置，不会清掉还没处理的提示。ArcReel 不会替你换模型。

全局与项目都没有设置某种媒体类型的默认模型时，生成使用自定义供应商里设为默认的模型；没有这样的模型就报错，设置页也会提示缺少默认模型。

从 0.36 及更早的版本升级后第一次启动时，ArcReel 把升级前自动使用的模型写进设置：

• 没有设置全局默认模型的媒体类型，写入升级前的版本会自动选中的预置模型；
• 项目设置里只选了预置供应商、没有选模型的项，补上升级前的版本会用的模型；
• 升级前就会报错的项（例如供应商的默认模型已被停用），升级后仍报错，提示重新选择模型；
• 升级前自动用的是自定义供应商的默认模型时，不写进设置，升级后照旧使用它。

升级前用的模型按升级前的版本与模型数据推算。少数情况推算不出，例如从 0.34 之前的版本或预览镜像升级：ArcReel 不替你挑模型，对应的默认模型留空，即使有设为默认的自定义供应商模型也不改用它，生成时报错，到「全局设置 → 默认模型」或项目设置里选择即可。

适合项目级覆盖的情况：

• 某个项目需要特定画风；
• 某个客户要求固定供应商；
• 不同项目预算差异明显；
• 需要比较两个供应商的效果；
• 某个地区只能访问部分服务。

3.1 启用与停用模型

预置供应商的详情页按文本、图片、视频、音频分组列出它的全部模型，每行显示模型名称、模型 ID 与价格摘要， 即将下线、已下线或调用会记为「未定价」的模型另有标记，即将下线的标记写明关停日期。用「全部 / 已启用」切换显示范围。 关停日期当天（按 UTC 日期）起模型视为已下线：它仍留在列表里，但即使手动启用过，也不再出现在任何模型候选里， 也不再作为供应商的推荐模型；已选了它的地方调用时报错，写明下线日期与官方建议改用的模型。 关停日期之前已经提交给厂商的视频任务不受影响：服务重启后续跑时照常取回结果。关停日期之后才提交的任务照常报错，包括关停前已排队、关停后才轮到提交的任务。

需要更新版本 ArcReel 才能调用的模型同样列在这里，排在所在分组末尾，标注「需要 ArcReel ≥ 版本号」。当前版本调用不了它：开关不可用，也不能打开模型设置；它不出现在任何模型候选里，也不作为供应商的推荐模型。升级到所需版本后，它和其他模型一样可以启用。

全局设置与项目设置里，默认模型、按用途指定的模型与配音模型选中了即将下线或已下线的模型时，下拉下方会写明下线日期与官方建议改用的模型。 官方建议的模型在同一个供应商下、并且可以用在这一处时，提示旁有「切换到 …」按钮：点击只改这一处的选择，保存后生效。 建议的模型在别的供应商下、已停用或不适用于这一处时，只显示它的名称。ArcReel 不会替你换模型。 选中的模型已不在供应商的模型清单里时，下拉下方同样有提示：ArcReel 收到过它的下线信息的，写明它已下线以及官方建议改用的模型（如果有）；没有收到过的，提示它已不可用，需要重新选择。

按用途指定模型时，下拉只能选中可以用在这一处的模型。默认模型的候选里有、但不能用在这一处的模型列在下拉末尾，写明原因，例如「不接受首帧」「不接受参考图」，不能选中。停用和已下线的模型不在其中。

• 关掉一个模型的开关即停用，立即生效：停用的模型不再出现在全局与项目的默认模型候选里，供应商的推荐模型被停用时， 不会写进默认模型，也不会提示切换到它；
• 已经在设置或项目里选中的模型停用后照常可用，需要换掉时到默认模型设置里另选；
• 旧版本中隐藏的 Agnes 旧模型升级后显示为停用，需要时可以重新启用。

价格摘要是各计费项的单价范围，按分辨率、时长等分档的模型显示最低到最高档。实际费用还要乘以供应商的倍率，倍率在同一页上方设置。

3.2 模型设置

点开模型列表里的一行，右侧打开这个模型的设置，预置供应商与自定义供应商相同。上半部分「供应商设置」只作用于当前供应商， 下半部分「模型信息」是这个模型在模型目录里的记录，所有使用这个模型的供应商共用。两部分共用底部的保存栏，在同一次保存里生效， 关闭前有未保存的修改会先询问。

• 所有模型都显示「这个供应商支持的参数」，即生效的能力与数值：模型目录的记录与调用端点支持范围都满足的部分，数量上限取两者中较小的那个。 两侧都没有记录的数值显示「未收录」，表示 ArcReel 没有收录这项限制，不代表可以随意传入，超出部分由供应商拒绝。 图片模型的参考图上限为 0 时不接受参考图，图生图同时显示为不支持，不会出现在图生图的候选里；
• 官方收录的内置模型在「供应商设置」里只能启用或停用，「这个供应商支持的参数」只能查看，由官方维护；「模型信息」的修改见下文；
• 自定义供应商的模型，以及在内置供应商下自己添加的模型，另有：
  • 「模型 ID」：调用时发给供应商的模型名称，改了以后，设置和项目里选中这个模型的地方需要重新选择；
  • 「倍率」：这个模型的倍率，供应商倍率不是 1 时会提示两者相乘后的最终倍率；
  • 修改「这个供应商支持的参数」：供应商实际支持的参数与模型信息不同时在这里修改，比如中转站只开放部分时长或分辨率， 或者不支持尾帧。每一项显示原值，点「修改」后整项替换，点「恢复」回到原值。对应不上已知模型的模型也可以修改。 图片模型可以修改「参考图上限」，整项替换模型信息与调用端点共同算出的上限；填 0 表示不接受参考图，点「恢复」回到原值。调用端点须实现图生图，修改上限才能用于这条路径。 视频模型的「按分辨率限定时长」跟在「可选时长」后面，删掉某个分辨率时， 它的时长限定一并删除；
  • 「从『供应商名』移除」：移除前先确认，设置或项目正在使用这个模型时，确认框会列出它们，移除后需要为它们改选其他模型；
• 在内置供应商下自己添加的模型另有「调用端点」，可选项只有这个供应商的调用端点，添加时按模型名称预填。 例如 MiniMax 的视频模型可以在「MiniMax Hailuo V1」「MiniMax Hailuo V1 Fast」「MiniMax S2V-01」与「MiniMax H3」之间选择。 更换后「这个供应商支持的参数」里的修改随之清除，保存后再按新的调用端点修改；
• 自定义供应商的模型另有「设为默认」「调用端点」「请求地址」与默认分辨率。更换调用端点后，修改过的请求地址恢复默认， 「这个供应商支持的参数」里的修改也随之清除，保存后再按新的调用端点修改。

「模型信息」可以修改显示名称、能力、可选时长、按分辨率限定时长、分辨率与最大输出长度；模型厂商、官方模型名、类型与别名只能查看。 顶部一行说明这些信息由谁维护：

• 官方维护：随官方数据更新。保存修改前，保存栏上方会提示「保存后，这个模型改用你修改的信息，不再随官方更新」；
• 你改过：官方数据更新时不会覆盖你的修改，模型列表里这一行标「已修改」。改过的字段下方显示官方值，点「采用」换回这一项的官方值； 点「恢复官方数据」并确认后，丢弃全部修改、回到官方数据，立即生效，不经保存栏，也无法撤销；
• 官方没有、由你填写：模型目录里原本没有这个模型的信息，也不会随官方更新。日后官方数据收录了同一个模型时， 这里出现「改用官方数据」：确认后，你填写的信息被官方数据替换，立即生效，也无法撤销。

中转站给模型改了名、按名字对应不上模型目录时，自己添加的模型和自定义供应商的模型可以手动指定对应的模型。 下半部分右上角的「关联其他模型」打开模型目录选择面板（默认只列同类型的模型），选中后能力、价格和调用通道的能力都按这个模型取得； 关联后不再按名字对应，点「解除关联」改回。目录里找不到的模型，点「手动填写」填写模型厂商、模型名称、显示名称、类型与能力， 视频模型的可选时长按模型名称预填；价格可以不填，不填时调用费用记为未定价。目录里已有同名的模型时不能填写，请直接选择它。 这些改动都只改草稿，随底部的保存栏一起生效，取消则不留下任何内容。

「模型信息」的「价格」一段按计费项分卡片编辑，也可以在这里补上目录里没有的价格：

• 先选币种（美元或人民币），价目表以模型厂商主站的币种标价，不做汇率换算；
• 「添加计费项」只列出这个类型的模型可用的计费项，如文本的「输入」「缓存命中」「输出」，视频的「视频时长」。不分条件的计费项一行单价； 点「按条件分价」加上分辨率、有声、服务档（标准、Flex、Fast）等条件后，每档一行「条件 → 单价」，点条件标签可以改取值，「添加一档」增加一行。 条件加上后不能移除，要换条件就删除整张卡片重新添加；
• 请求没有给出某个条件时，按卡片下方「请求没有给出条件时按」一行的取值计价，没有设置的条件取不到价格，这次调用记为未定价；
• 参考图这类计费项可以「添加免费额度」，每次请求超出额度的部分才计费；
• 不填价格时，调用费用记为未定价。条目被改过时，价格下方显示官方价格，点「采用官方价格」换回；币种与官方不同时不显示对比。

其他供应商也使用这个模型时，「模型信息」会列出它们：修改与恢复官方数据都会对这些供应商一起生效。 只想表达某个供应商与模型信息不同（如中转站只开放部分时长）时，改「这个供应商支持的参数」，不要改模型信息。

自定义供应商的名称、接口地址、密钥、并发上限与供应商倍率仍在供应商详情里统一保存，保存时不会改动模型列表里的模型。

使用记录的详情里，点模型名可以直接打开这个模型的设置；供应商已删除或是 Agent 凭证时只显示模型名。

3.3 添加模型与获取模型

模型列表上方有「添加模型」与「获取模型」两个入口，预置供应商与自定义供应商都有。

「添加模型」可以搜索模型名称，或直接输入模型 ID，并按媒体类型筛选：

• 「未启用的模型」：只在预置供应商下出现，列出停用的官方收录模型，选中即启用；
• 「按模型 ID 添加」：按输入的模型 ID 添加。媒体类型先按模型目录对应，对应不上时按模型名称推断， 筛选了媒体类型时按所选类型；
• 「模型目录」：从模型目录选一个模型添加，这个模型的价格与模型信息都按所选条目计。已在列表里的条目标为「已添加」； 预置供应商已收录这个模型时（API 模型名可能与目录里的名字不同），选中即启用收录的那个模型。

添加后会直接打开新模型的设置，可以接着修改调用端点等设置。

升级前已提交的内置供应商视频任务完成前，请保留该模型的调用端点。旧任务没有记录端点身份，更换端点可能导致续跑失败，但不会重新提交生成。

「获取模型」调用供应商的模型列表接口，只列出还没有添加的模型，已添加的只显示数量。结果分两组：

• 「已识别」：对应上模型目录中的已知模型，默认勾选；
• 「未识别」：默认不勾选。名字能对应上模型目录中的条目的，行里显示对应的模型名，添加后按它计价；对应不上条目、 或条目没有价格的，行里提示调用费用会记为「未定价」。可以为每一行点「对应模型」从模型目录选一个，添加后按所选模型计价。

自定义供应商的每一行另有调用端点下拉，默认值按模型名称推断，选了对应模型时改按它的媒体类型推断。获取失败时显示失败原因， 可以检查接口地址与密钥后重试。

预置供应商中，AI Studio、Vertex AI、OpenAI、Grok、阿里百炼、MiniMax 与 Agnes 支持获取模型，需要先添加密钥。 供应商返回的模型 ID 必须与官方收录模型的 API 模型名完全一致才算「已识别」。供应商列出某个模型，不代表当前账号或地区一定能调用它； 同样，没有列出的官方收录模型也照常保留在列表里。

4. 选择供应商的六个维度

不要只看单次生成效果。

4.1 质量

关注：

• 角色身份保持；
• 商品结构保持；
• 画面构图；
• 动作自然度；
• 文本遵循；
• 长镜头稳定性；
• 输出分辨率。

4.2 可控性

关注是否支持：

• 多参考图；
• 首尾帧；
• 负面提示词；
• 固定种子；
• 视频延展；
• 参考生视频；
• 原生音频；
• 结构化输出。

4.3 可靠性

关注：

• API 成功率；
• 排队时间；
• 限流行为；
• 超时；
• 任务查询；
• 幂等性；
• 失败后是否可安全重试。

4.4 成本

比较时应使用同一个完整分镜目标，而不是只比较单价。

总成本可能包括：

• 文本 Token；
• 角色、场景和道具图片；
• 分镜图片；
• 视频秒数；
• 失败重试；
• TTS；
• 因质量问题产生的返工。

4.5 速度

区分：

• API 响应时间；
• 排队时间；
• 实际生成时间；
• 高峰期波动；
• 批量任务并发能力。

4.6 合规和可用地区

确认：

• 账号所在地区；
• API 是否在部署地区可用；
• 内容政策；
• 数据处理要求；
• 商业使用条款；
• 生成内容标记要求。

5. 推荐的分层策略

5.1 经济型验证

用于：

• 新项目试跑；
• 提示词验证；
• 分镜数量确认；
• 分镜动作方向测试。

策略：

• 少量内容；
• 快速文本模型；
• 低成本分镜模型；
• 快速视频档位；
• 严格限制批量数量。

5.2 平衡型生产

用于：

• 常规批量内容；
• 已验证的角色和风格；
• 需要稳定吞吐。

策略：

• 关键资产使用高质量模型；
• 普通分镜使用平衡模型；
• 视频按分镜重要度分层；
• 为失败重试保留预算。

5.3 高质量交付

用于：

• 关键剧情；
• 封面分镜；
• 商品特写；
• 品牌交付；
• 需要更高分辨率的成片。

策略：

• 高质量参考图；
• 更严格的分镜审核；
• 先做低成本预演；
• 只对确认后的分镜使用高成本模型；
• 保留人工后期。

6. 图像供应商配置

图像能力主要用于：

• 角色设计；
• 场景和道具设计；
• 商品标准参考图；
• 单个分镜；
• 多宫格分镜；
• 风格分析和图像编辑。

选择时重点关注：

• 多参考图支持；
• 角色和商品身份保持；
• 文字和 Logo 表现；
• 目标比例和分辨率；
• 图像编辑能力；
• 失败时返回的错误信息。

建议：

• 角色资产图尽量使用背景简单、主体完整的构图；
• 商品参考图优先使用真实素材和多角度输入；
• 普通分镜不必全部使用最高成本模型；
• 先固定角色和风格，再批量生成。

在项目设置的「模型」分页和创建项目向导里，图片模型下方可以选择分辨率。支持画质参数的图片模型还提供「画质」，与分辨率分别选择；画质选「自动（按分辨率档位）」时，由分辨率档位决定画质。不支持画质参数的模型不显示这一项。

已保存的分辨率或画质不在当前模型的可选值中时，例如模型不再提供某个分辨率档位，设置页会在对应字段下方提示。生成时仍按已保存的值请求，可能被供应商拒绝；点提示旁的按钮可以恢复默认分辨率或自动画质。

7. 视频供应商配置

视频能力可能覆盖：

• 文生视频；
• 图生视频；
• 参考生视频；
• 首尾帧；
• 视频延展；
• 原生音频；
• 固定种子；
• 不同时长和分辨率。

选择前确认：

• 当前模型支持的输入类型；
• 参考图数量限制；
• 单次时长；
• 横竖屏支持；
• 是否会生成有声视频；
• 任务查询和取消能力；
• 失败是否计费；
• 内容审核规则。

不要假设所有视频模型支持相同参数。ArcReel 会统一上层工作流，但供应商特有能力仍然存在差异。

8. 文本供应商配置

文本能力用于：

• 结构化剧本；
• 提示词生成；
• 多模态理解；
• 费用预估中的文本调用；
• 自定义辅助任务。

关注：

• JSON 或结构化输出稳定性；
• 长上下文；
• 中文表现；
• 视觉理解；
• 速度；
• Token 价格；
• 限流。

高推理模型不一定适合所有任务。可把复杂内容分析和普通结构化转换分给不同模型。

9. TTS 配置

ArcReel 的旁白能力可以使用阿里百炼 Qwen TTS 与 qwen-audio TTS、MiniMax 语音、Gemini TTS（AI Studio、Vertex）、Grok TTS、火山方舟 Agent Plan 的豆包语音合成模型 2.0 或兼容的 TTS 接口。

在全局设置和项目设置里选定 TTS 模型后，旁白音色输入框会列出这个模型可选的常用音色。列表之外的音色（例如复刻音色）照供应商文档填写音色 ID。

阿里百炼语音分为两个调用端点：「阿里百炼（语音合成）」调用 Qwen TTS（qwen3-tts 等），「阿里百炼（qwen-audio 语音合成）」调用 qwen-audio TTS（qwen-audio-3.0-tts、qwen-audio-3.1-tts 系列）。两个端点的音色不通用，qwen-audio 的各个模型也只能使用各自的音色，完整列表见百炼音色列表。qwen-audio 端点支持配音语速，范围 0.5～2.0，超出范围时按最近的边界值提交。添加模型时，名称含 qwen-audio 的模型预填 qwen-audio 端点，其余百炼语音模型预填 Qwen TTS 端点，在模型设置里可以修改。

Grok TTS 的配音语速范围是 0.7～1.5。超出范围时合成任务在提交前失败，不产生费用，也不会自动改成边界值，需要在设置里调整或清空配音语速。

火山方舟 Agent Plan 的语音合成使用已配置的 Agent Plan 专属 API Key，不需要另外填写 AK/SK，调用的是套餐内的专属语音接口。套餐未开通语音合成、并发已用尽、音色未授权，或套餐额度已用尽且没有开启超额后付费时，合成任务失败并显示上游错误码。ArcReel 不会改用按量付费的语音接口；如果在方舟控制台开启了超额后付费，月额度用尽后的调用会照常完成，超出部分由方舟按后付费出账，以方舟账单为准。音色列表只列出「豆包语音合成模型 2.0」的常用中文音色，其他 2.0 音色按官方音色列表填写音色 ID，1.0 音色不能使用。配音语速范围是 0.5～2.0，超出范围时合成任务在提交前失败，不产生费用。使用记录里的字符数取接口回报的计费字符数，接口未回报时按提交文本的字符数统计。

配置后先验证：

• 中文和英文发音；
• 人名、地名和专有名词；
• 数字和单位；
• 语速；
• 情绪；
• 单段最大长度；
• 输出音频格式。

批量生成前，先试听一段包含典型专有名词的文本。

10. 自定义供应商

ArcReel 可以接入 OpenAI 兼容或 Google 兼容服务。典型用途：

• 自建 API 网关；
• 企业统一密钥管理；
• 私有模型服务；
• 本地 Ollama 或 vLLM 周边服务；
• 第三方兼容平台。

一般配置包括：

• 名称；
• Base URL；
• API Key；
• 模型名称；
• 媒体类型；
• 可选的供应商特有参数。

模型发现协议只决定 ArcReel 使用哪类模型列表接口；每个模型实际如何调用，由它绑定的调用端点决定。ArcReel 可以按模型名称推断媒体类型和调用端点，但兼容协议不代表所有能力和参数都可用，添加后可以在模型设置里调整，也应逐项验证：

1. 文本连通性；
2. 结构化输出；
3. 图片生成；
4. 视频任务创建；
5. 视频任务查询；
6. TTS；
7. 错误码和限流行为。

模型名称会按模型目录对应已知模型：忽略大小写，忽略最后一个 / 之前的命名空间，点号视同连字符。对应上的模型，可选时长、分辨率、最大输出长度等信息和价格都取自模型目录；对应不上的模型照常可用，视频的可选时长按模型名称推断，费用记为「未定价」。

对应上的模型同样随模型目录即将下线与已下线：列表上显示同样的标记。已下线的模型不再出现在任何模型候选里，也不再作为自定义供应商的默认模型；已选了它的地方调用时报错，写明下线日期与官方建议改用的模型，不会改用这个供应商的默认模型，停用了它也一样。

视频模型的文生视频、首尾帧、参考图和参考音频，取模型目录的记录与调用端点支持范围都满足的部分，参考图与参考音频的数量上限取两者中较小的那个。对应不上已知模型的视频模型，文生视频和首帧按调用端点的支持范围，尾帧和参考音频不可用，参考图数量只受调用端点限制。图片模型能否用于文生图和图生图同样取两侧都满足的部分，参考图上限取两者中较小的那个；对应不上已知模型时，按调用端点的支持范围。需要不同的值时，在模型设置里修改「这个供应商支持的参数」，或把模型对应到模型目录中的已知模型。ComfyUI 调用端点例外：输入能力只由 workflow 的节点绑定决定，不读模型目录，也不能在模型设置里修改，见接入 ComfyUI workflow。

通过 OpenRouter 接入图片模型时，在模型设置里把调用端点改为「OpenRouter 图片」。OpenRouter 不提供 OpenAI 的 /images/edits 接口，挂在「OpenAI 图片」上的模型无法图生图；「OpenRouter 图片」的文生图与图生图都走 /images，比例、清晰度和参考图上限按 OpenRouter 对该模型声明的参数确定。参考图多于该模型的上限时，只发送前面的参考图，并在任务结果中提示；任一张参考图读取失败时，生成直接报错，不会少带参考图继续生成。

通过自定义供应商接入火山方舟 Seedream 时，3.x 选择「Seedream (1K)」，4.x 及后续代际选择「Seedream (2K)」。名称含 seedream-3 的模型预填 1K 端点，其余名称含 seedream 的模型预填 2K 端点；内置方舟与方舟 Agent Plan 下自己添加的模型也可选择这两个端点。端点决定未指定分辨率时使用的尺寸表，显式指定的分辨率仍原样发送。文生图与带参考图生成复用同一份参考图处理和计量。各模型的具体限制见方舟官方图片生成 API 文档。升级时，已有模型按此前的请求约定自动设置端点；已保存为「OpenAI 图片」的 Seedream 模型保持原选择。若供应商不支持当前的参考图接口，按提示在模型设置里选择对应的 Seedream 端点后重试。

阿里百炼图片的调用端点区分「Qwen 融合」「Qwen 编辑」与「Wan」，分别按总像素预算、单边像素限制与 Wan 的默认尺寸计算请求。模型可选分辨率来自模型目录；Wan 带参考图时最高使用 2K。Agnes 图片的调用端点区分「像素尺寸」与「档位与比例」：前者发送宽高，后者分别发送分辨率档位和画面比例，按各自请求格式计量。已有模型升级后保持此前的请求约定；自行添加模型时按名称预填，也可在模型设置里修改。

通过自定义供应商接入火山方舟 Seedance 时，按模型的代际选择调用端点「火山方舟 (Seedance 1.x)」「火山方舟 (Seedance 2.0)」或「火山方舟 (Seedance 2.5)」，在内置火山方舟与方舟 Agent Plan 下自己添加的模型同样在这三个端点中选择。三个端点调用同一个接口，区别在请求参数与计费：

• 1.x 发送服务档参数，按服务档计费；
• 2.0 与 2.5 不发送服务档参数，提交前按视频 token 预估费用，两者的分辨率与像素对照不同；
• 2.5 带首帧时，画面比例交给供应商按首帧自适应。

名称写明 2.0 或 2.5 的模型默认推断到对应端点，其余名称含 seedance 的模型推断到 1.x。模型 ID 不带代际时（例如方舟推理接入点 ID），在模型设置里改为对应的端点。已添加的模型在升级时按此前实际使用的代际自动设置，升级前提交的视频任务照常续跑。

内置 Agnes 下自己添加的视频模型，按模型代际选择「Agnes（视频 2.0）」或「Agnes（视频 2.5）」：2.0 输出无声视频，2.5 输出有声视频。分辨率限制来自模型目录条目，不根据型号名中的 flash 判断。

百炼异步视频按请求方式分为通用视频、固定有声视频、参考生视频、参考图配音视频和 Wan3 视频。参考生视频必须带参考图；参考图配音把音频逐项绑定到参考图；Wan3 可以切换音轨，并可使用单独的 MaaS 接口地址。添加模型时按名称预填，在模型设置里可以修改。已有模型在升级时按此前使用的请求方式自动设置，升级前提交的任务可以继续取回结果。

Veo 的音轨开关由调用方式决定：AI Studio 固定有声，Vertex AI 可以切换音轨。Gemini Omni 经 Interactions API 调用，在 AI Studio 与 Vertex AI 下对应调用端点「Gemini 视频 (Omni)」与「Vertex AI 视频 (Omni)」，Veo 仍是两者的默认调用端点。Omni 的成片固定有声，只能在提示词里描述想要的声音；首尾帧与参考图不能同时使用，也不能单独使用尾帧。自己添加的模型名称含 gemini-omni 时预填 Omni 端点，包含 gemini-omni-1.2-*。自定义供应商也可选择「Gemini 视频 (Omni)」，使用 API Key 连接兼容 Interactions API 的服务，并分别覆盖提交与轮询路径；Vertex AI 版仍只供内置供应商使用。Sora 是否支持 1080p 由模型目录条目的分辨率决定，不根据型号名中的 pro 判断。

可灵视频有两套请求格式。旧版 API 在参数里指定型号，按尾帧与音轨的请求约定分为四个调用端点；新版 API 把型号名写在请求路径里，对应调用端点「Kling 视频（新版 API，固定有声）」，用于 kling-4.0、kling-4.0-flash、kling-3.0-turbo 这类只在新版 API 上提供的型号。新版 API 只支持 API Key 鉴权，内置可灵只填写了 Access Key 与 Secret Key 时无法使用这个端点。这个端点的成片固定有声，没有音轨开关；目前支持文生视频和首尾帧，不支持参考图与参考视频。添加名称为上述型号的模型时，会预填这个端点。

需要的调用端点如果已经有人适配过，可以从市场直接安装，不必自己编写定义。

供应商以 JSON 提交任务、再用任务 ID 轮询 JSON 结果时，可以在「调用端点」分区点击「新建端点」，自己编写声明式定义。

声明式定义对视频与图片供应商都适用：定义写 "media_type": "image" 即为图片定义，不写即为视频定义。图片定义挂到自定义供应商的图片模型后，可用于分镜图与资产图生成；声明了图生图能力的图片定义还可用于图片编辑。

新建时可以在「示例模板」中选择视频或图片的「提交 + 轮询」模板作为起点，选择模板会替换当前草稿。

自建 ComfyUI 可以直接导入 API 格式 workflow，并把提示词、素材、尺寸、时长与产物映射到节点；完整步骤与运行限制见接入 ComfyUI workflow。

中转站沿用官方协议、只改了路径（加前缀、改版本段或换路径名）时，可以在模型设置里修改「请求地址」。调用端点发出的每条请求各占一行，接口地址部分灰显，点击路径即可修改：按 Enter 或点击别处保存，按 Esc 取消。修改后的路径直接接在供应商填写的接口地址之后，不再自动补 /v1 或剥去版本段。只想去掉自动补上或剥去的部分时，点开路径不作修改，直接按 Enter。路径中只能使用这条请求本身已有的占位符，例如 {{ model }}、{{ task_id }}。路径带 ? 查询参数时，会整体替换原请求的查询参数；原请求中需要保留的参数（例如 Gemini 下载地址的 alt=media）要一并写进修改后的路径。

测试连接和真实生成都按修改后的地址发出，获取模型和连通性检查仍按接口地址发出。更换调用端点后，修改过的请求地址会恢复默认。视频任务提交后又修改了请求地址时，服务重启后的续跑会直接失败，不会重新提交。模型设置里没有「请求地址」一栏的调用端点不支持修改。

10.1 端点测试三模式

在设置页的调用端点详情中，可以按风险从低到高使用三种测试模式：

• 验证响应：粘贴供应商的提交、查询或取件响应样本，检查每条取值路径、状态映射和错误字段； 不向供应商发送请求，也不产生费用。图片定义的 base64 路径命中时，只显示取到的图片字节数， 不回显整串。
• 预览请求：用示例参数渲染将要发送的 URL、方法、请求头和请求体，供你对照供应商文档； 同样不向供应商发送请求，也不产生费用。
• 测试连接：真实提交一次生成并跟踪到终态。界面以计费徽章标明这一模式会产生一次调用费用； 必需素材端点须先上传对应的首帧、尾帧、参考图或参考音频。

测试连接进行中可以取消。取消会停止 ArcReel 对这次测试的跟踪并清除本地结果，但供应商的远端任务 可能仍会继续，已经发生的费用仍会记入账本。成功的视频产物直接在结果卡中播放，图片产物直接 显示；调用编号可跳转到费用账本。终态结果与产物由服务端保留 24 小时，之后不再可查。

10.2 用 Agent 适配自定义调用端点

视频或图片供应商采用 JSON 提交任务、再用任务 ID 轮询 JSON 结果时，可以把适配交给 Claude Code 等 外部 Agent。签名鉴权、发往供应商的 multipart 请求或按素材切换路由不在声明式定义首期范围内。

安装公开 skill：

npx skills add ArcReel/skills

在安装列表中同时选择 setup-arcreel-skills 与 adapt-custom-endpoint。也可以直接查看或下载同一份适配 skill 源文件。

先使用 setup-arcreel-skills skill 完成 ArcReel MCP 接入；它会在当前工作区持久化同一连接，供 adapt-custom-endpoint 的本地脚本跨会话复用。

然后让 Agent 读取供应商文档并使用该 skill。它会按「写定义 → 共享 validator 校验 → 离线验证 响应 → 预览请求 → 测试连接 → 保存」执行；定义格式和薄 HTTP 脚本随 skill 一起下载，适配过程不新增 MCP 或 SDK tool。验证响应 与 预览请求 不向供应商发请求；测试连接 会真实生成并可能计费， Agent 必须先取得你的明确同意。检测到同作者、同名的定义时，另存副本可以直接执行，覆盖既有端点必须先 取得你的明确同意。

必需素材通过 CLI 的 --start-image、--end-image、可重复的 --reference-images 和可重复的 --reference-audio-files 传入；这些参数使用与设置页相同的 multipart 字段。

11. 多 API Key

同一供应商可以配置多个 API Key，并选择当前激活 Key。

使用多个 Key 时应遵守供应商条款。它适合：

• 不同项目或客户隔离；
• 测试和生产隔离；
• 额度管理；
• 凭据轮换。

它不应被用于规避供应商限流、风控或服务条款。

密钥轮换建议：

1. 新增新 Key；
2. 用小任务验证；
3. 切换激活；
4. 观察错误率；
5. 删除或停用旧 Key；
6. 更新密钥管理记录。

12. 对象存储与供应商素材库

火山方舟与 BytePlus 的供应商素材库保存经过审核的素材，生成时以 asset:// 引用。全局设置的「素材库与存储」分区管理对象存储与素材库相关的配置。这些配置都可以不填，没有这些配置时本地项目照常工作。

• 对象存储：你自己的 TOS 存储桶，填写区域、Endpoint、桶名与 Access Key。只保存连接不改变图片的保存位置，新增图片默认仍保存在本地；要把新增图片保存到这个桶，另在「新增图片保存位置」中选择「对象存储」，见新增图片保存到对象存储。Endpoint 填 TOS Endpoint（如 tos-cn-beijing.volces.com），不支持 tos-s3- 开头的 S3 兼容 Endpoint。保存后可以用「测试连接」确认凭证与桶可以访问。
• 素材库账号：访问素材库控制面的 Access Key，与推理用的 API Key 分开保存，需要具备素材库权限。添加账号时选择站点（火山引擎中国站或 BytePlus 国际站）并填写项目，默认项目为 default。供应商按项目隔离素材，推理凭证需要属于同一个项目。控制面请求只发往所选站点的官方地址，不使用推理凭证的 Base URL。供应商素材只属于创建它的云账号，所以关联与入库任务记下的是账号当时的 Access Key ID 所属的云账号。把账号的 Access Key ID 换成另一个后，原有关联保留在原来的云账号下，不再用于生成，未完成的入库任务也不会用新的 Access Key 继续推进；需要在这个账号下重新上传或选择图片。只修改 Secret Access Key 不影响已有关联。
• 推理凭证绑定：为每条火山方舟密钥或自定义供应商选择它可以使用的素材库账号。修改推理凭证的密钥或 Base URL，或修改账号的站点、项目与 Access Key ID 后，绑定显示「需要重新确认」，确认前不使用该账号的素材。绑定只表示你确认这条推理凭证与账号对应，供应商仍按自己的权限校验每次调用。

所有 Access Key 只在设置页输入，读取时只显示首尾几位。

上传图片到素材库

在项目资产卡片或角色详情中衍生的更多操作菜单中选择「上传到供应商素材库」，可以为每个素材库账号上传这张图片当前选中的版本。上传前需要配置对象存储：ArcReel 把图片副本写进你的存储桶，签发 24 小时内有效的下载地址交给供应商，再提交入库，因此 ArcReel 不需要公网地址。

• 供应商异步审核入库，状态依次为「等待上传」「提交中」「供应商处理中」，完成后变为「可用」或「失败」。关闭窗口不影响入库，只有「可用」的关联会用于生成。失败时显示供应商返回的错误码与原因。
• 关联属于图片的具体版本。入库期间改选其他版本，结果仍归属提交时的版本；新选中的版本需要另行上传，切回旧版本时仍可使用旧版本的关联。
• 提交请求的结果不确定（如网络中断）时，状态显示「结果待确认」。ArcReel 按提交记录在素材库中查找这次上传的素材，不会重复创建。长时间没有结果时，可以解除关联后重新上传。
• 「解除关联」只解除 ArcReel 中的关系，不删除 ArcReel 图片，也不删除供应商素材库中的素材。供应商素材的改名与删除在供应商控制台进行。解除后可以重新上传。
• 首次上传时，ArcReel 在账号的项目里创建名为 ArcReel 的素材组。供应商要求创建素材组前在控制台签署授权，未签署时上传失败并显示供应商的错误码。

存储桶里的中转副本都在 arcreel-relay/ 前缀下，由 ArcReel 后台自动清理：入库有结果后，副本自写入起至少保留 1 小时再删除；一直没有结果时，保留到下载地址过期后 1 小时。删除失败时自动重试，清理不涉及桶内其他对象。删除连接或更换桶、Endpoint 时，可立即删除或放弃这些副本，见更换或删除连接。

图片已经保存到对象存储时，不另写中转副本，直接为桶里的这张图片签发下载地址。入库期间在 ArcReel 中删除这张图片并彻底清除，桶里的图片也按上面的期限保留，供应商仍能取图，期满后不再被使用时才删除。

从素材库选择已有图片

在项目资产卡片或角色详情中衍生的更多操作菜单中选择「从供应商素材库选择」，可以按账号查看素材库里的素材名称、类型与可用状态，并选择一张已入库的图片作为这张资产图或衍生图。选择不需要配置对象存储。

• 只有状态为「可用」的图片素材可以选择。ArcReel 向供应商查询素材，从供应商返回的访问地址取回原图，再按上传图片的方式保存为一个新版本：新版本出现在版本历史里，可以预览、局部修改，也可以切回之前的版本。
• 新版本自动与所选素材建立「可用」的关联，关联记录素材库账号的站点、区域与项目。之前的版本不继承这个关联。
• 取不回原图时不导入，例如素材已在供应商侧删除、访问地址已失效或网络中断。素材原图须为 PNG、JPEG 或 WebP 格式，大小不超过 30 MB。导入失败时图片保持原来的版本，也不建立关联，可以稍后重试或换一张素材。
• 导入不压缩、不缩放原图，确保保存的版本与供应商素材一致：资产图保留原图内容；衍生图固定以 PNG 格式保存，PNG 原图原样保存，JPEG 与 WebP 原图按原像素转为 PNG。

保存到全局资产库与应用到其他项目

把项目资产保存到全局资产库，或把全局资产库里的资产应用到其他项目时，资产图与衍生图当前版本的「可用」关联随图片一起带过去，仍属于原来的素材库账号、站点、区域与项目。

• 带过去的是关联的副本，由各自的项目或全局资产库独立持有：在一处解除关联或换图，不影响其他副本。
• 生成时仍按这次实际使用的推理凭证判断关联是否适用。推理凭证绑定的是另一个账号时，带过去的关联不适用，照常发送图片内容。
• 只带「可用」的关联。尚在入库或入库失败的任务不带过去，需要时在目标项目里重新上传。
• 删除来源项目或资产后，全局资产库和已经应用的项目照常可用，供应商素材库中的素材也不会被删除。

项目 ZIP 与供应商素材关联

导出项目 ZIP 时，包里图片版本的「可用」关联随图片一起带走，仍属于原来的素材库账号、站点、区域与项目。在另一台 ArcReel 导入后，推理凭证绑定的素材库账号与原账号属于同一个云账号时，生成直接使用这些素材，不需要重新上传。

• 导入的关联只在推理凭证绑定的账号与原账号属于同一个云账号、且站点、区域与项目都相同时使用；否则关联保留但不使用，照常发送图片内容。素材能否使用最终由供应商按账号判断。
• 只带「可用」的关联。尚在入库、结果待确认或入库失败的任务不带，导入后在目标项目里重新上传。
• 「仅当前版本」的 ZIP 只带随包的版本的关联。没有随包带上版本记录的图片（例如生成的资产图）不带关联。
• ZIP 里不含素材库账号的 Access Key、签名地址或对象存储信息。包里的图片被改过时，对应的关联不导入，图片照常导入。

生成时使用素材库

参考生视频提交前，ArcReel 先确定视频通道这次实际使用的推理凭证，找到这条凭证已确认绑定的素材库账号，再逐张检查参考图当前选中的版本在这个账号里有没有关联。上传与导入建立的关联按同样的规则使用。

• 关联可用：这张参考图以 asset:// 素材引用发出，其余参考图照常发送图片内容。参考图的数量、顺序与提示词里的图片编号不变。
• 没有适用的关联：照常发送图片内容。推理凭证没有绑定或绑定需要重新确认、当前版本没有上传或导入过、模型不接受素材引用时，都按没有适用的关联处理。
• 关联尚未可用或入库失败：关联处于「等待上传」「提交中」「供应商处理中」「结果待确认」或「失败」状态时，不改发图片内容，也不向供应商提交请求。提交前的检查、批量生成预览与费用预估就会指出这个问题，不给出这一单元的预估费用；执行时再按实际发出的图片检查一次，状态在提交之后才变化的，生成在执行时失败。提示点名第几张图片：可以等入库可用后再生成；入库失败时提示中带有供应商的错误码。也可以解除关联，改发普通图片。

只有火山方舟与 BytePlus 的 Seedance 2.0 与 2.5 系列模型的参考图使用素材引用。是否适用看模型挂接的调用端点，不看模型 ID 本身：调用端点为「火山方舟 (Seedance 2.0)」或「火山方舟 (Seedance 2.5)」时适用，「火山方舟 (Seedance 1.x)」不适用。内置供应商与自定义供应商的模型按同一规则判断。首帧、尾帧、分镜图与图片生成仍然发送图片内容。切换推理凭证后，按新凭证的绑定重新判断，之前账号里的关联不再适用。

供应商以输入图片未通过审核拒绝请求时（错误码以 InputImageSensitiveContentDetected 开头，例如 InputImageSensitiveContentDetected.PrivacyInformation），ArcReel 不自动上传、不重试生成，也不切换供应商。错误提示给出供应商的错误码，并提示把相关资产图上传到供应商素材库，等入库可用后重新生成。只有请求里只有一张参考图、没有首帧和尾帧时，提示才点名这张图片；供应商的错误不指明是哪张图片时，提示不猜测。被拒的图片已经以素材引用发出时，提示改为在供应商控制台检查该素材。

在对话中使用素材库

ArcReel Agent 和通过远程 MCP 连接的外部 Agent 可以完成同样的素材库操作，与资产卡片使用同一组关联记录：

• 查询一张图片当前版本的关联与入库状态，以及可用的素材库账号；
• 浏览素材库账号里已有的素材，并把你选定的图片保存为资产图的新版本；
• 在你明确要求时，把指定图片上传到素材库；
• 在你同意后解除关联，ArcReel 图片与供应商素材都不删除。

Agent 只在你明确要求时上传。生成被供应商审核拒绝后，Agent 会转述原因并说明可以上传，由你决定，不自动上传或重新生成。上传后 Agent 立即得到入库任务，不等待供应商审核；你可以稍后让 Agent 查询状态。素材库账号、对象存储与推理凭证绑定仍在「素材库与存储」分区配置，Agent 看不到其中的密钥，也不能改名或删除供应商素材库中的素材。

新增图片保存到对象存储

对象存储连接默认只用于素材入库时中转图片。要让新增图片持久保存在桶里、本地只保留可以清理的缓存，在「素材库与存储」分区的「新增图片保存位置」中选择「对象存储」。这是实例的全局设置，默认「本地」，没有按项目或按图片的选项。

最小配置

1. 配置对象存储连接，并用「测试连接」确认凭证与桶可以访问。
2. 在「新增图片保存位置」中选择「对象存储」，选中后立即生效。没有配置连接时不能选择。

连接的 Access Key 需要对这个桶上传、读取（含查询对象信息）与删除对象的权限；「测试连接」只检查能否访问桶，不检查这些对象权限。删除权限用于清理中转副本、回收不再使用的图片对象。

生效范围

• 设置只影响之后新保存的图片版本：生成与局部修改的图片、宫格图与切分出的分镜图、手动上传的资产图、分镜图、衍生图与宫格图、从素材库选择的图片、导入的项目 ZIP，以及保存到全局资产库和应用到项目的图片。
• 已有图片与历史版本不搬迁，仍从各自原来的位置读取。切回之前的版本、从回收站恢复，都沿用那个版本原来的位置，不算新保存的图片。
• 改回「本地」只影响之后新保存的图片，桶里已有的图片照常读取。同一个项目里可以同时有本地图片与远端图片。
• 以下图片不建版本历史，始终保存在本地：分镜的尾帧、角色原图与商品原图、项目的风格参考图。视频与音频也始终保存在本地。

中转副本与图片对象

桶里有两类对象，分别管理：

前缀	内容	清理方式
arcreel-relay/	素材入库时的中转副本	入库有结果或下载地址过期后由后台删除，见上传图片到素材库
arcreel-materials/	保存到对象存储的图片，按内容命名，同样的图片只存一份	只要还有版本历史、回收站、已删除项目、全局资产库、其他项目或入库中的任务在用就保留；不再被任何一处使用（如在回收站中彻底删除）后由 ArcReel 删除

不要在 TOS 控制台手动删除或改写 arcreel-materials/ 下的对象，否则对应图片无法预览、生成或导出。中转清理不涉及这些对象。

本地缓存

远端图片在本地有一份缓存，供预览、生成与图片处理直接使用。缓存只是副本，清理后需要时自动从对象存储取回并核对内容，打开工作台、查看状态不会触发下载。

• ArcReel 后台每小时清理一次闲置超过 24 小时的缓存。
• 需要立即释放空间时，调用 POST /api/v1/object-storage/work-cache/cleanup。请求体可以带 min_idle_seconds，只清理闲置超过这个秒数的缓存，缺省为 0。返回清理的文件数 removed、释放的字节数 freed_bytes，以及因正在使用而保留的文件数 kept_in_use。
• 清理只删除已确认保存在对象存储、且与远端内容一致的缓存；本地图片、正在使用的文件与桶里的对象都不受影响。

备份与迁移

• 远端图片的内容只在桶里，备份 ArcReel 数据目录不包含它们。启用后需要同时保留这个桶。ArcReel 会删除不再使用的图片对象，要能恢复较早的备份，须同时备份桶里 arcreel-materials/ 下的对象，或为桶开启版本控制，见备份与恢复。
• 迁移到另一台 ArcReel 时导出项目 ZIP。导出前 ArcReel 先取回缓存已清理的远端图片，ZIP 里是图片的实际内容，不含桶名或访问密钥；另一台 ArcReel 按自己的「新增图片保存位置」重新保存这些图片。

更换或删除连接

• 桶里还有项目、回收站、全局资产库等正在使用的图片对象，或有图片正在保存时，不能更换桶、Endpoint 或区域，也不能删除连接，只能更新 Access Key。没有引用或只被入库任务使用的图片对象不影响更换或删除连接。
• 「新增图片保存位置」为「对象存储」时不能删除连接，先改回「本地」。
• 保存图片的同时更换了连接，这次保存失败、保留原来的图片，重试后保存到新的桶。
• 项目正在删除或被导入的项目替换时，保存到这个项目的图片会失败，项目原有的图片不受影响。
• 删除连接或更换桶、Endpoint 时，默认勾选「同时删除 ArcReel 写入桶里的待删除文件」。ArcReel 会用当前凭证立即删除没有引用的图片对象、只被入库任务使用的图片对象及全部中转副本，不等待保留期。更换桶或 Endpoint 时，保持勾选保存前会再次确认。只改区域时不显示此选项，原有保留与清理规则不变。
• 取消勾选后，桶内文件不动，ArcReel 清除对应记录。勾选后删除失败的，页面报告一次失败数量和原因，连接仍照常变更，记录同样清除。放弃或删除失败的文件可在原桶的控制台清理，ArcReel 不再自动重试；桶内其他文件不受影响。
• 有未定论的入库任务时，对话框提示数量。连接离开旧桶后，受影响的任务会失败；原图仍在 ArcReel，解除关联后可重新上传。

故障处理

• 提示「图片没能保存到对象存储」：这次的新版本不会出现，之前的版本、产物与文件不变。用「测试连接」确认连接，检查 Access Key 的上传权限与网络后重试；也可以先改回「本地」继续创作。导入项目 ZIP 时出现这个提示，这次导入没有写入任何项目，检查连接后重新导入。
• 区域、Endpoint 或桶填错，图片一直保存失败：先把「新增图片保存位置」改回「本地」，再编辑连接改正，或删除连接后重新配置。保存失败的图片没有被任何地方使用，不妨碍修改。改正 Endpoint 或桶时，对话框显示清理选项，已有记录按「更换或删除连接」的规则处理。原 Endpoint 不可达时，删除失败按网络原因报告一次，记录照常清除；这些对象没有写进桶里，不需要处理。写进过原来的桶但没有删除成功的，需要在 TOS 控制台清理。不要按前缀批量删除 arcreel-materials/ 下的对象：改正前后是同一个桶时，其中有正在使用的图片。
• 预览、生成或导出时提示「没能从对象存储取回这张图片」：这张图片在桶里的对象缺失、被改写，或暂时无法访问。检查网络与读取权限；对象被删除或改写时，从回收站或其他版本恢复，或重新生成、上传。
• 提示图片保存在原来的对象存储桶里，当前连接已删除或指向另一个桶：连接的桶或 Endpoint 已不是保存这张图片时的设置。把连接改回原来的桶与 Endpoint 后即可读取。
• 提示新增图片设为保存到对象存储，但还没有配置连接：配置连接，或把「新增图片保存位置」改回「本地」。
• 保存图片变慢：图片在保存版本的过程中上传到对象存储，确认保存后才出现新版本。上传期间，同一项目的其他图片保存会排队等待；图片较大或网络较慢时更明显。导入项目 ZIP 时，图片在导入请求中逐张上传。

13. 费用追踪

ArcReel 可以按供应商和媒体类型记录费用，但需要注意：

• 不同供应商使用不同计费单位；
• 不同币种不应直接混为一个未经说明的总数；
• 供应商价格可能调整；
• 某些失败任务也可能产生费用；
• 实际账单以供应商结算为准。

内置供应商的文本、配音、图片与视频调用，费用按模型的官方价格计算：

• 缓存命中与缓存写入按各自的单价计，不按普通输入计；
• 按输入长度分档的模型，按单次请求的输入总量（含缓存）落档，整个请求用同一档的单价；
• 官方按「汉字计 2」计价的配音模型，每个汉字按 2 个字符计；
• 图片按实际发给供应商的分辨率、质量档落档；请求里没有带分辨率时，按供应商的默认档计；
• 官方对参考图另行收费的图片模型（如超出免费张数的参考图），参考图按张计入；
• 视频按实际生成的秒数，以及发给供应商的分辨率、是否有声与时长档计；Vidu 的参考生视频按它自己的单价计；
• 方舟 Seedance 按视频 token 计费：结算取供应商回报的 token 数，提交前预估按官方公式（宽 × 高 × 帧率 × 秒数 / 1024）换算， 画面比例交给供应商自适应时算不出 token 数，预估记为「未定价」；
• 查不到适用单价的调用记为「未定价」，不按其他模型或其他档的价格估算。

自定义供应商的模型不单独填价格。模型名称能对应到模型目录中的已知模型时，按这个模型的官方价格计费，规则与内置供应商相同； 对应不上时，这个模型的调用记为「未定价」。设置页的模型列表会显示每个模型对应到的已知模型，对应不上的显示「未定价」。

每个供应商可以设置一个倍率，乘在这个供应商全部调用的费用上，用来表达充值折扣或中转站价差。 自定义供应商的模型和在内置供应商下自己添加的模型还可以再设一个倍率，最终费用 = 官方价格 × 供应商倍率 × 模型倍率。例如中转站整体按官方价的 八折收费，把供应商倍率设为 0.8；其中某个模型另按官方价的 1.5 倍收费，把这个模型的倍率设为 1.875（0.8 × 1.875 = 1.5）。 倍率默认是 1；方舟 Agent Plan 按订阅计费，ComfyUI 供应商跑在你自己的机器上，这两类倍率默认是 0，不计算费用。修改倍率只影响之后的调用， 已经记下的费用不会重算。

Agent 会话的费用按同一套模型目录计算，不采用 Claude Agent SDK 回报的费用：

• 每次模型请求按自己的 token 用量与输入总量计价，子智能体的请求一并计入；
• 每轮对话中用到的每个模型各记一条，模型名是实际调用的模型；
• 模型名对应不到模型目录中的已知模型时，照常记下 token，费用记为「未定价」；
• 压缩上下文等在消息流里看不到的调用，按 SDK 回报的累计用量补齐；恢复会话后的第一轮没有可比较的基准，这类调用不计入。

每个 Agent 供应商可以设置一个倍率，乘在经这个供应商的全部 Agent 调用的费用上，默认是 1。按订阅计费的网关可以把倍率设为 0，不计算费用。会话按开始（或恢复）时生效的 Agent 供应商计费，倍率与下文手动选择的模型也取那一刻的设置。会话进行中切换生效的供应商、修改倍率或手动选择的模型，都不影响已经开始的会话，之后开始（或恢复）的会话才按新设置计费。已经记下的费用不会重算。

设置页的 Agent 供应商列表会列出主模型与 Haiku、Sonnet、Opus、子智能体四个档位实际调用的模型名，以及每个档位是否已定价、对应到模型目录中的哪个模型。对应不上的档位显示「未定价」，这个档位的调用会记为「未定价」。Anthropic 官方预设留空的档位由 Claude Code 决定调用哪个模型，费用按实际调用的模型名计算。

未定价的档位可以点「选择模型」，从模型目录里手动选一个模型，之后这个档位的调用按所选模型计价；点「解除绑定」回到按模型名自动对应。手动选择只保存在这个 Agent 供应商上，不修改模型目录里的条目，也不影响条目的官方更新。所选模型之后从目录中消失时，档位回到按模型名对应，并提示「所选模型已下线」，此时仍可以解除绑定。

建议把 ArcReel 费用追踪用于：

• 项目预算；
• 分镜成本比较；
• 模型选择；
• 异常调用发现；
• 预估与实际偏差分析。

它不替代供应商官方账单。

14. 故障排查

连通性检查失败

检查：

• API Key；
• Base URL；
• 模型名称；
• 网络代理；
• TLS 证书；
• 账号地区；
• 账户余额或额度。

文本能用，图片或视频不能用

同一供应商的不同媒体能力可能：

• 使用不同端点；
• 需要单独开通；
• 使用不同模型名称；
• 有不同地区限制；
• 需要异步任务查询。

频繁限流

降低：

• RPM；
• 并发任务数；
• 单次批量分镜数。

同时确认是否有多个 ArcReel 实例共享同一 Key。

费用明显高于预估

检查：

• 是否重复提交任务；
• 是否发生多次重试；
• 是否切换了更高价模型；
• 实际视频时长是否增加；
• 是否生成了原生音频；
• 价格表是否需要更新；
• 供应商是否调整计费方式。

15. 文档更新原则

供应商模型变化频繁，因此：

• README 只维护能力矩阵；
• 本文维护配置原则；
• 具体模型列表以设置页为准；
• 官方价格以供应商页面为准；
• ArcReel 新增或移除供应商时，应同时更新矩阵、设置页帮助信息和测试。