企业官网建设流程全解析

AIGC视频制作的核心问题，往往不是某个单一工具能不能生成画面，而是脚本、分镜、视频片段、字幕和成片拼接之间如何连贯衔接。使用Claude和Higgsfield做自动化AI视频制作（中文字幕），本质上就是把大模型的内容规划能力与视频生成平台的渲染能力组合成一条可重复执行的生产链路：Claude负责把一段主题描述拆成带分镜、时长、提示词和中文字幕文本的JSON脚本，Higgsfield负责按提示词逐段生成视频，最后通过FFmpeg把字幕烧录进画面并合并成完整成片。

这篇文章的目标是带你搭一个最小可用的自动化流水线。阅读前不需要非常熟悉Claude和Higgsfield的全部功能，但最好有基本的Python读写能力和命令行操作经验。你会看到环境准备、目录结构、API调用方式、字幕时间轴计算、FFmpeg烧录和常见问题排查。最终，当你有一个具体选题时，只需要改一句需求描述，就能跑出一段带中文字幕的AI视频素材。

需要先说明一点：Higgsfield的具体接口字段、Claude的模型可用性和API地址都会随平台版本变化。文中的代码会使用通用占位结构，落地到项目时，要以你实际开通的账号权限和官方API文档为准。

1. 先理解Claude和Higgsfield在流水线中的分工

1.1 Claude负责内容规划，而不是直接渲染画面

Claude是一个大语言模型产品，擅长文本生成、语义理解和结构化输出。在AI视频制作流水线里，Claude适合做三类工作：

• 把一句选题描述扩展成多个分镜，每个分镜包含画面描述、镜头运动和风格要求。
• 为每个分镜生成对应的中文字幕文案，保证视频画面和字幕内容一致。
• 把以上内容统一输出成JSON结构，方便后续脚本读取和处理。

不要把Claude当成视频渲染引擎。Claude不能直接生成视频文件，也没有能力决定Higgsfield最终会渲染出什么画面。它真正解决的是“内容组织”问题。同样一个主题，直接让人工在Higgsfield里逐条输入提示词，效率低且难以批量复制。用Claude生成结构化分镜脚本后，下游脚本可以按JSON字段自动处理，这是整个自动化流程的基础。

1.2 Higgsfield负责把提示词变成视频片段

Higgsfield是一个AI视频生成平台，使用提示词生成短视频片段，也支持从静态图片生成视频。相比直接用Claude写一大段描述然后手工上传到网页，自动化流水线更适合通过API或官方支持的批量方式提交生成任务。

在本文的设计中，Higgsfield承担的是“渲染层”：

• 接收一个英文或中文的提示词。
• 根据提示词生成对应时长的视频片段。
• 返回视频文件地址或可下载的临时链接。

需要承认的是，不同时期Higgsfield对API的开放程度可能不同。如果当前平台只提供网页端，没有开放API，那么自动化方案需要改用浏览器自动化工具或者官方批量上传能力。本文以“存在API接口”为前提展开，代码结构会留出替换空间。

1.3 自动化链路：一条命令完成“脚本到成片”

整个流水线可以描述为：

需求文本 -> Claude API 生成 scenes.json -> Higgfield API 逐段生成视频片段 -> 本地脚本根据 scenes.json 生成 SRT 字幕 -> FFmpeg 烧录字幕并拼接片段 -> 最终成片 final.mp4

这样的链路有三个直接收益：

1. 可重复：同样一个Python脚本，换一个主题描述，就能生成一套新的分镜和视频。
2. 可追踪：每一段视频的prompt、生成状态、失败原因都能记录到日志文件。
3. 可扩展：以后加入配音、背景音乐、片头片尾，只需要在流水线中插入新步骤。

如果只是偶尔做一两条视频，手工操作足够。但当你需要一天产出多条短视频，或者需要反复调整分镜和字幕时，自动化流水线就比网页手工操作稳定得多。

2. 环境准备：装好Claude Code、配置API密钥和项目目录

2.1 前置条件与建议版本

在开始之前，先确认本机环境满足以下条件。

FFmpeg不是只在最后拼接时用到。字幕烧录、格式转换、编码统一都要靠它。学习环境可以先安装，不用理解全部参数，但至少要会用ffmpeg -version验证安装成功。

Claude Code是Anthropic提供的命令行编程工具，可以用交互方式辅助写脚本。在本项目中，我们也会使用它的安装方式和认证流程，但真正的流水线脚本统一通过Python调用API，这样更容易批量执行。

2.2 安装Claude Code并完成认证

在终端执行：

npm install -g @anthropic-ai/claude-code

安装完成后，验证命令是否可用：

claude --version

如果输出类似1.0.x的版本号，说明安装成功。继续执行：

claude

首次运行会进入授权流程。你需要在终端提示的引导下完成账号登录。如果只是写自动化脚本，也可以不依赖Claude Code，直接使用ANTHROPIC_API_KEY环境变量调用API。两者并不冲突：

• Claude Code适合开发调试阶段，比如让Claude帮你写脚本、解释报错。
• API Key适合生产流水线，比如在无人值守的服务器上批量跑任务。

不要把API Key写死在代码里。推荐放到项目根目录的.env文件中，并在.gitignore中忽略它。

2.3 获取Higgsfield API密钥并写入环境变量

登录Higgsfield控制台后，找到API密钥管理页面。不同平台的入口名称可能不一样，常见叫法有API Keys、Access Tokens、开发者设置。创建一个密钥后，把它和其他配置一起写入.env。

ANTHROPIC_API_KEY=sk-ant-你的Claude密钥 CLAUDE_MODEL=你的Claude模型名 HIGGSFIELD_API_KEY=hf-你的Higgsfield密钥 HIGGSFIELD_API_BASE=https://api.higgsfield.ai HIGGSFIELD_VIDEO_VERSION=v1

这里的配置说明：

• CLAUDE_MODEL不一定写死。不同账号可用的模型列表不同，建议以控制台实际显示的模型ID为准。
• HIGGSFIELD_API_BASE一般填写平台提供的API域名。如果平台没有开放API，这一项可以先留空，后续脚本需要替换为官方支持的接入方式。
• 密钥文件不要提交到git仓库。如果使用GitHub，检查.gitignore是否包含.env。

2.4 安装Python依赖并准备目录结构

在项目根目录创建requirements.txt：

requests>=2.31.0 python-dotenv>=1.0.0

本教程使用requests库进行HTTP调用，不依赖具体厂商的SDK。这样做的好处是，即使某个平台的SDK更新频繁，核心逻辑仍然是一致的。安装依赖：

pip install -r requirements.txt

然后创建目录结构：

ai-video-pipeline/ ├── .env ├── .gitignore ├── requirements.txt ├── scripts/ │ ├── 01_generate_script.py │ ├── 02_generate_video.py │ ├── 03_make_subtitles.py │ └── 04_burn_subtitles.py ├── fonts/ │ └── NotoSansCJK-Regular.otf └── output/ ├── scripts/ ├── videos/ ├── subtitles/ └── final/

fonts目录用来存放中文字体文件。后面烧录字幕时会用到。如果系统已有中文字体，也可以不复制到项目目录，但把它放进项目目录会让移植到其他机器时更省事。

3. 用Claude生成结构化视频脚本和分镜

3.1 用Prompt让Claude输出固定JSON

自动化流水线最怕的是模型返回内容格式不稳定。Claude如果输出一长段带标题的文本，下游Python脚本就很难直接解析。因此，在设计Prompt时，必须明确要求输出固定JSON，并且不输出任何额外说明。

示例Prompt：

你是一个短视频分镜导演。用户会给你一个视频主题， 你需要把它拆成多个镜头。 每个镜头必须包含以下字段： - scene_id: 字符串，例如 scene_01 - prompt: 英文视频生成提示词，描述画面内容、镜头运动和风格 - duration: 整数，表示这一镜头视频的秒数，范围3到6 - subtitle_text: 这一镜头对应的中文字幕文案 要求： 1. 只输出JSON数组。 2. 不要输出JSON之外的任何解释。 3. 不要使用Markdown代码块包裹。

为什么要用英文prompt？因为很多视频生成模型对英文提示词的理解更稳定，中文也能处理，但英文准确率通常更高。中文字幕文案则单独存在subtitle_text字段里，后续用它生成SRT文件。

3.2 编写第一个Claude调用脚本

新建scripts/01_generate_script.py：

import os import json import requests from dotenv import load_dotenv load_dotenv() ANTHROPIC_API_KEY = os.environ.get("ANTHROPIC_API_KEY") CLAUDE_MODEL = os.environ.get("CLAUDE_MODEL") if not ANTHROPIC_API_KEY or not CLAUDE_MODEL: raise SystemExit("请先在 .env 中配置 ANTHROPIC_API_KEY 和 CLAUDE_MODEL") url = "https://api.anthropic.com/v1/messages" headers = { "x-api-key": ANTHROPIC_API_KEY, "anthropic-version": "2023-06-01", "content-type": "application/json", } system_prompt = """ 你是一个短视频分镜导演。用户会给你一个视频主题， 你需要把它拆成多个镜头。 每个镜头必须包含以下字段： - scene_id: 字符串，例如 scene_01 - prompt: 英文视频生成提示词，描述画面内容、镜头运动和风格 - duration: 整数，表示这一镜头视频的秒数，范围3到6 - subtitle_text: 这一镜头对应的中文字幕文案 要求： 1. 只输出JSON数组。 2. 不要输出JSON之外的任何解释。 3. 不要使用Markdown代码块包裹。 """ user_content = "主题：城市夜景与科技生活，成片总时长约30秒" payload = { "model": CLAUDE_MODEL, "max_tokens": 4000, "system": system_prompt, "messages": [{"role": "user", "content": user_content}], } resp = requests.post(url, headers=headers, json=payload, timeout=120) resp.raise_for_status() content_text = resp.json()["content"][0]["text"] scenes = json.loads(content_text) os.makedirs("output/scripts", exist_ok=True) with open("output/scripts/scenes.json", "w", encoding="utf-8") as f: json.dump(scenes, f, ensure_ascii=False, indent=2) print(f"已生成 {len(scenes)} 个分镜")

关键点有三个：

• 使用anthropic-version请求头是Anthropic API的约定，缺少这部分可能会报错。
• system_prompt承担了约束输出格式的任务，它比在user内容里临时要求更稳定。
• 对json.loads的调用必须放在try except中，否则模型一旦输出非JSON，脚本会直接中断。

3.3 分镜JSON的关键字段与校验

正常生成的output/scripts/scenes.json类似：

[ { "scene_id": "scene_01", "prompt": "aerial view of city at night, neon lights, cyberpunk style, cinematic lighting", "duration": 5, "subtitle_text": "夜幕降临，城市的灯光开始苏醒。" }, { "scene_id": "scene_02", "prompt": "close-up of a person using a transparent smartphone, futuristic ui overlay, shallow depth of field", "duration": 5, "subtitle_text": "科技正在改变我们与世界的连接方式。" } ]

这里的duration是后续视频生成的字长参数，也是字幕时间轴的计算基础。如果Claude输出的duration不在3到6范围内，或者缺少subtitle_text，下游流程可能出错。因此推荐在保存前做一次简单校验：

required_fields = {"scene_id", "prompt", "duration", "subtitle_text"} for scene in scenes: missing = required_fields - set(scene.keys()) if missing: raise ValueError(f"分镜 {scene.get('scene_id')} 缺少字段: {missing}")

校验逻辑放在01_generate_script.py的保存逻辑之前。这样越早发现问题，浪费的API调用就越少。

3.4 常见坑：Claude返回非JSON内容

模型有时候会输出这样的内容：

好的，我为你生成了以下分镜： [ ... ]

如果直接json.loads(content_text)，会因为前面的“好的”两个字导致解析失败。解决方式有两种：

1. 在Prompt里反复强调只输出JSON。
2. 在代码里做容错处理，比如去掉内容前后的Markdown代码块标记。

简单容错写法：

def parse_json_from_text(text): text = text.strip() if text.startswith("```"): text = text.strip("`") if text.startswith("json"): text = text[4:] return json.loads(text)

这个函数示例只处理最基础的Markdown包裹情况。更稳妥的方式是让Claude输出后，如果解析失败，就把原始文本写入output/scripts/raw_response.txt，方便人工查看问题原因。

4. 调用Higgsfield批量生成视频片段

4.1 Higgsfield视频生成API的通用结构

不同视频生成平台的API字段差异较大，但通常都会包含以下几个概念：

• prompt：提示词。
• duration：视频时长。
• resolution：分辨率，例如720p或1080p。
• aspect_ratio：画面比例，例如16:9或9:16。
• watermark：是否携带平台水印。

以通用结构为例：

creation_payload = { "prompt": "aerial view of city at night, neon lights, cyberpunk style", "duration": 5, "resolution": "720p", "aspect_ratio": "16:9", "watermark": False, }

这里选择720p而不是1080p，主要有两个原因：

1. 生成速度快，适合学习环境反复调试。
2. 生成成本更低，避免失败重试时浪费额度。

当整个流程跑通后，再切换到1080p。不要在一开始就追求最高分辨率，因为分辨率越高，排队时间和失败概率通常也越高。

4.2 创建生成任务并轮询状态

新建scripts/02_generate_video.py：

import os import json import time import requests from dotenv import load_dotenv load_dotenv() HIGGSFIELD_API_KEY = os.environ.get("HIGGSFIELD_API_KEY") HIGGSFIELD_API_BASE = os.environ.get("HIGGSFIELD_API_BASE", "https://api.higgsfield.ai") if not HIGGSFIELD_API_KEY: raise SystemExit("请先在 .env 中配置 HIGGSFIELD_API_KEY") HEADERS = { "Authorization": f"Bearer {HIGGSFIELD_API_KEY}", "Content-Type": "application/json", } def create_video(prompt, duration): payload = { "prompt": prompt, "duration": duration, "resolution": "720p", "aspect_ratio": "16:9", } resp = requests.post( f"{HIGGSFIELD_API_BASE}/v1/video/generations", headers=HEADERS, json=payload, timeout=30, ) resp.raise_for_status() return resp.json()["id"] def wait_video(generation_id, interval=8, timeout=600): start = time.time() while time.time() - start < timeout: resp = requests.get( f"{HIGGSFIELD_API_BASE}/v1/video/generations/{generation_id}", headers=HEADERS, timeout=30, ) resp.raise_for_status() data = resp.json() status = data.get("status") if status == "succeeded": return data.get("video_url") if status in ("failed", "canceled"): raise RuntimeError(f"生成失败: {data.get('error') or status}") time.sleep(interval) raise TimeoutError("等待生成超时") def download_video(url, path): with requests.get(url, stream=True, timeout=120) as r: r.raise_for_status() with open(path, "wb") as f: for chunk in r.iter_content(chunk_size=8192): f.write(chunk) def main(): with open("output/scripts/scenes.json", encoding="utf-8") as f: scenes = json.load(f) os.makedirs("output/videos", exist_ok=True) for scene in scenes: scene_id = scene["scene_id"] prompt = scene["prompt"] duration = scene["duration"] print(f"[{scene_id}] 开始生成: {prompt}") try: gen_id = create_video(prompt, duration) print(f"[{scene_id}] 任务ID: {gen_id}") video_url = wait_video(gen_id) output_path = f"output/videos/{scene_id}.mp4" download_video(video_url, output_path) print(f"[{scene_id}] 视频已保存: {output_path}") except Exception as e: print(f"[{scene_id}] 生成失败: {e}") with open("output/failures.jsonl", "a", encoding="utf-8") as f: f.write(json.dumps({"scene_id": scene_id, "error": str(e)}, ensure_ascii=False) + "\n") if __name__ == "__main__": main()

这段脚本有几个特意设计的点：

• 失败任务不会让整个流水线直接中断，而是把错误信息追加到output/failures.jsonl，方便后续单独重试。
• 每个scene按顺序执行，避免并发请求触发限流。
• download_video使用流式下载，避免视频文件较大时一次性读入内存。

4.3 限流与并发控制

如果Higgsfield支持并发，也不要一上来就开10个线程。原因是API Key通常有每分钟请求数限制，视频生成也需要排队，并发过高的代价是429限流错误和大量失败任务。

学习环境建议串行生成。等熟悉了平台的返回状态后，再尝试把并发数控制在2到3个。更稳的方式是使用线程池加信号量：

from concurrent.futures import ThreadPoolExecutor, as_completed with ThreadPoolExecutor(max_workers=2) as executor: futures = { executor.submit(process_scene, scene): scene["scene_id"] for scene in scenes } for future in as_completed(futures): scene_id = futures[future] try: future.result() print(f"[{scene_id}] 完成") except Exception as e: print(f"[{scene_id}] 失败: {e}")

但这只是并发框架，实际还需要根据平台限制调整max_workers。不要照抄这个并发方案到一个免费账号上，先确认限制再上线。

4.4 常见坑：任务长时间peding和失败

视频生成平台通常是异步任务，提交后会进入排队。status为queued或processing都是正常状态。如果长时间停在queued，需要检查：

• 是否提交了过长的prompt。
• 是否包含平台不支持的关键词。
• 当前账号是否还有剩余额度。
• 分辨率或时长是否超出套餐限制。

如果从任务创建到轮询超过15分钟仍然没有结果，建议主动记录错误，而不是无限等下去。wait_video中的timeout参数就是为此设置的。

5. 用Claude生成中文字幕并用FFmpeg烧录

5.1 字幕文案已经由Claude生成了，为什么还要单独处理

在第三步生成分镜时，每个scene已经带有subtitle_text字段。这部分文案就是中文字幕。不需要再调用一次Claude生成字幕，否则会浪费token，也可能让字幕和画面描述不一致。

真正需要做的，是把JSON里的字幕文本和时长转换成标准SRT格式文件，再通过FFmpeg烧录进视频。SRT是一种广泛支持的字幕格式，结构简单：

1 00:00:00,000 --> 00:00:05,000 夜幕降临，城市的灯光开始苏醒。

其中每个字幕序号后的时间表示字幕开始时间和结束时间，单位是小时:分钟:秒,毫秒。

5.2 Python生成SRT文件

新建scripts/03_make_subtitles.py：

import os import json def to_srt_timestamp(seconds): hours = int(seconds // 3600) minutes = int((seconds % 3600) // 60) secs = int(seconds % 60) millis = int(round((seconds - int(seconds)) * 1000)) return f"{hours:02}:{minutes:02}:{secs:02},{millis:03}" def build_srt(scenes): lines = [] idx = 1 cursor = 0.0 for scene in scenes: duration = float(scene.get("duration", 5)) text = scene.get("subtitle_text", "").strip() if text: end_time = cursor + duration lines.append(str(idx)) lines.append( f"{to_srt_timestamp(cursor)} --> {to_srt_timestamp(end_time)}" ) lines.append(text) lines.append("") idx += 1 cursor += duration return "\n".join(lines) def main(): with open("output/scripts/scenes.json", encoding="utf-8") as f: scenes = json.load(f) os.makedirs("output/subtitles", exist_ok=True) all_srt = build_srt(scenes) for idx, scene in enumerate(scenes): scene_id = scene["scene_id"] single_scene_srt = build_srt([scene]) srt_path = f"output/subtitles/{scene_id}.srt" with open(srt_path, "w", encoding="utf-8") as f: f.write(single_scene_srt) all_path = "output/subtitles/all_scenes.srt" with open(all_path, "w", encoding="utf-8") as f: f.write(all_srt) print(f"已生成字幕文件: output/subtitles/")

这段脚本会为每个分镜单独生成一份SRT，同时生成一个包含全部字幕的all_scenes.srt。单场景SRT用于给单独的视频片段烧录字幕，全部字幕文件可以用来检查整体时间轴。

时间轴设计的核心逻辑是：每个scene的字幕开始时间等于前一个scene的结束时间。也就是说，第一段视频从第0秒开始，第二段视频从第一段结束的瞬间继续。这样做成的成片，字幕不会错位。

5.3 FFmpeg烧录中文字幕的完整命令

假设要给output/videos/scene_01.mp4烧录字幕：

ffmpeg -y -i output/videos/scene_01.mp4 \ -vf "subtitles=output/subtitles/scene_01.srt:force_style='FontName=Noto Sans CJK SC,FontSize=18,Outline=1,Shadow=0'" \ -c:v libx264 -c:a aac -pix_fmt yuv420p \ output/final/scene_01.mp4

说明：

• subtitles滤镜会把SRT文件中的文字渲染到画面上。
• force_style用来指定字体、字号、描边和阴影。
• -pix_fmt yuv420p是为了兼容更多播放器。
• 如果原视频没有音频轨，-c:a aac会自动处理，不会报错。

中文字幕最容易出现的问题是字体。如果系统里没有名为Noto Sans CJK SC的字体，FFmpeg会报找不到字体，或者字幕显示为方框。可以先在系统里查看可用中文字体：

fc-list :lang=zh

在Linux环境，如果缺少字体，可以安装：

sudo apt install fonts-noto-cjk

在Windows环境，可以把字体名改成Microsoft YaHei：

-vf "subtitles=output\\subtitles\\scene_01.srt:force_style='FontName=Microsoft YaHei,FontSize=18'"

Windows下还要注意路径中的反斜杠和冒号转义。推荐把输出目录和脚本都用相对路径，并把字体文件放到项目fonts目录，降低路径问题出现的概率。

5.4 合并片段时的编码一致性

如果多个片段的编码参数不同，直接拼接可能失败。先创建一个文本文件filelist.txt：

file 'output/final/scene_01.mp4' file 'output/final/scene_02.mp4' file 'output/final/scene_03.mp4'

然后执行拼接：

ffmpeg -y -f concat -safe 0 -i filelist.txt -c copy output/final/final.mp4

-c copy是直接复制音视频流，速度很快，但要求所有片段编码格式一致。如果无法保证，就统一重新编码：

ffmpeg -y -f concat -safe 0 -i filelist.txt -c:v libx264 -c:a aac output/final/final.mp4

重新编码会更慢，但兼容性更好。在批量执行前，可以先手动检查两个片段的编码信息：

ffprobe -v error -show_entries stream=codec_name -of default=noprint_wrappers=1 output/final/scene_01.mp4

这里要注意：如果单个片段生成时就带有不同帧率，比如一个30fps一个24fps，重新编码时可以加上-r 30统一帧率，否则拼接出来的画面会有卡顿。

6. 串联流水线并验证成片

6.1 用一个Shell脚本按顺序执行

四个Python脚本可以手动依次执行，但更推荐用一个Shell脚本封装：

#!/usr/bin/env bash set -euo pipefail python scripts/01_generate_script.py python scripts/02_generate_video.py python scripts/03_make_subtitles.py python scripts/04_burn_subtitles.py echo "pipeline finished"

其中set -euo pipefail的作用是：

• -e：遇到错误立即退出。
• -u：使用未定义变量时报错。
• -o pipefail：管道中任意命令失败都会让整个管道失败。

这样就不会出现某个脚本失败后，后续脚本仍然继续执行的情况。保存为run_pipeline.sh后，给予执行权限：

chmod +x run_pipeline.sh ./run_pipeline.sh

6.2 验证输出文件与关键信息

流水线运行完成后的预期结构：

output/ ├── scripts/ │ └── scenes.json ├── videos/ │ ├── scene_01.mp4 │ ├── scene_02.mp4 │ └── ... ├── subtitles/ │ ├── scene_01.srt │ ├── all_scenes.srt ├── final/ │ ├── scene_01.mp4 │ ├── scene_02.mp4 │ └── final.mp4

验证步骤建议：

1. 打开output/scripts/scenes.json，确认分镜数量和字幕文案完整。
2. 播放output/videos/scene_01.mp4，确认画面与提示词匹配。
3. 播放output/final/scene_01.mp4，确认字幕文字正常显示。
4. 播放output/final/final.mp4，确认片段衔接连贯、字幕时间轴连续。
5. 检查总时长：

ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 output/final/final.mp4

总时长应接近scenes.json里所有duration之和。

6.3 从需求变更到重新生成的迭代方式

当你想换一个视频主题时，只需要修改脚本里的主题描述，或者把主题作为命令行参数传入：

python scripts/01_generate_script.py "主题：清晨的森林与自然治愈"

更工程化的做法是让01_generate_script.py接收一个外部参数：

import sys user_content = sys.argv[1] if len(sys.argv) > 1 else "主题：城市夜景与科技生活"

这样每次重新生成分镜时，不需要改代码，只需要改命令。整个流水线可以进入“批量选题”模式。

7. 常见问题与排查链路

7.1 Claude相关安装与调用问题

Claude Code安装和API调用环节，最容易出现以下几类问题。

排查这一类问题，建议按顺序检查：

1. 环境变量是否加载。
2. 命令是否真的安装成功。
3. API Key是否有效。
4. 模型名是否可用。
5. 日志中的HTTP状态码是什么。

7.2 Higgsfield生成任务失败

视频生成平台的错误信息通常比较明确。当resp.raise_for_status()抛出异常后，不要只打印“请求失败”，要打印响应体内容：

except requests.HTTPError as e: print(e.response.text)

这样能看到平台返回的具体错误码和错误消息。

7.3 中文字幕乱码或缺失

FFmpeg烧录字幕时，最推荐的做法是把中文字体放进项目目录，并在force_style中直接指定字体文件路径。这样可以减少系统字体差异带来的问题。

7.4 通用排查链路

当整个流水线出问题时，不要急着改代码。先按下面的顺序判断：

1. 输入是否正确：检查scenes.json是否生成，字段是否完整。
2. 文件路径是否正确：确认Python脚本在项目根目录运行，而不是在scripts目录内运行。
3. 依赖版本是否匹配：检查Python依赖和FFmpeg版本。
4. 配置是否生效：打印.env中的关键环境变量是否存在。
5. 网络和权限是否正常：确认API地址可达、API Key有效。
6. 日志是否出现明确异常：读取output/failures.jsonl和FFmpeg的报错信息。
7. 平台限制：确认当前账号的生成额度、队列长度和步骤是否足够。

8. 最佳实践与后续扩展

8.1 学习环境与生产环境的差异

学习环境和生产环境对系统的要求完全不同。不要在学习环境跑通后，直接当作生产流程使用。

生产环境还需要考虑成本控制。视频生成不是免费的，一个失败的重复任务也会消耗额度。建议在任务创建时记录prompt、分辨率、时长和任务ID，方便月底对账。

8.2 成本控制与可观测性

一个实用的做法是输出结构化日志。比如每次生成完成后，追加一行JSON：

{ "scene_id": "scene_01", "generation_id": "gen_xxx", "prompt": "aerial view of city at night", "status": "succeeded", "duration": 5, "cost_credit": 10 }

有了这样的日志，就可以统计每天消耗了多少调用量，也能快速定位哪类提示词最容易失败。

重试策略也要加。如果Higgsfield返回429限流，直接重试大概率还是429。正确做法是读取响应头中的Retry-After值，等一段时间再重试。如果返回400参数错误，重试没有意义，应该先修正参数。

8.3 可复用上线前检查清单

在把自动化流水线接入正式发布流程前，建议逐项确认：

• [ ] API密钥已配置，且.env未提交到git仓库。
• [ ]CLAUDE_MODEL和Higgsfield接口字段已按官方文档核对。
• [ ] 本机已安装中文字体，FFmpeg字幕渲染不报错。
• [ ] 所有分镜的duration总时长和final.mp4实际时长差值在1秒以内。
• [ ] 至少抽查3个成片，确认字幕、画面、转场正常。
• [ ] 失败任务会记录到日志，并有重试机制。
• [ ] 已设置输出目录的磁盘空间监控。
• [ ] 生产环境使用异步回调或任务队列，而不是长时间轮询。
• [ ] 已确定最终发布渠道的视频分辨率和编码要求。

8.4 扩展方向：TTS、配乐和人工审核

当前流水线只解决了画面和字幕。实际短视频通常还需要旁白和背景音乐。扩展方向很清晰：

1. 接入TTS服务，把subtitle_text转成配音音频。
2. 在FFmpeg合并后混入背景音乐，并用-shortest保证视频长度与音频长度匹配。
3. 在成片完成后，加入一个人工审核步骤，避免AI生成的画面出现不合适内容。
4. 把scenes.json和生成的视频作为素材库，方便以后做系列内容。

对于新手，建议先从2到3个镜头的短视频开始，跑通“需求->脚本->视频->字幕->成片”全流程后，再去优化并发、成本和画面质量。自动化视频制作的真正价值不在于一次生成多震撼的画面，而在于让“内容策划”和“视频渲染”两个环节可以独立迭代。Claude负责把想法变成结构化的拍摄脚本，Higgsfield负责把脚本变成画面，FFmpeg负责把画面和字幕变成可发布的成片。把这套链路跑通之后，后续你换主题、换风格、换成片时长，都是在同一个框架上做参数级调整。