AutoGPT Platform 视频发布实战：使用 Ayrshare「Post To YouTube」块上传与调度 YouTube 视频

导读：在 AutoGPT Platform 的 Agent/Graph 编排中，Post To YouTube 是接入 Ayrshare 社交发布 API、面向 YouTube 单平台优化的上传块。本指南以其官方文档为骨架，结合仓库中 post_to_youtube.py 与 Ayrshare 客户端实现 源码，完整讲解全部输入/输出字段、平台级参数校验、Ayrshare API 字段映射、凭据链路与计费规则。读完你将能够在 AutoGPT 工作流中稳定地发布普通视频与 Shorts、设定可见性/定时/分区/字幕，并在运行失败时获得可排查的结构化错误输出。

一、这是什么：块的定位与核心能力

Post To YouTube（块 ID 0082d712-ff1b-4c3d-8a8d-6c7721883b83，见 ayrshare/init.py）是 AutoGPT Platform 的社交发布块族（Ayrshare 系列）中专门面向 YouTube 的一个。它不是一个从零实现的 YouTube Data API 上传器，而是 Ayrshare「Social Media Post API」的封装：AutoGPT 侧负责凭据管理、平台参数校验、成本核算与流程编排，真正的视频转码、上传与元数据落库由 Ayrshare 服务端完成。

从块注册信息看（post_to_youtube.py）：

• categories={BlockCategory.SOCIAL}：归属于「社交」分类，可在 Builder 中与 AI 生成、文件处理、定时器等其它块自由连线；
• block_type=BlockType.AYRSHARE：由统一的 Ayrshare 块基础设施提供凭据与客户端；
• 块本身是纯异步的：run() 在构造 AyrshareClient 后调用其 create_post()，通过生成器以 yield 方式产出 error、post_result 等输出流。

在实际的端到端链路中，该块的 media_urls 输入既可以来自「下载/生成视频」块，也可以来自 URL 提取块；schedule_date 或 publish_at 配合定时触发器即可实现"内容自动生产 → YouTube 自动排期"的无人值守流程。

二、运行前提：凭据、渠道关联与链路

虽然文档的输入参数表未列出凭据，但每个实际运行都必须经过 Ayrshare 凭据链路，其由三部分组成。

1. 组织级密钥（管理员配置）。AyrshareClient 构造时读取服务端配置中的 AYRSHARE_API_KEY 作为 Authorization: Bearer 请求头（ayrshare.py）。未配置时抛出 MissingConfigError；post_to_youtube.py 会将此情形转换为输出 error: Ayrshare integration is not configured. Please set up the AYRSHARE_API_KEY.。另需 AYRSHARE_JWT_KEY（见下方可用性检查）。

2. 用户级 profile 凭据（自动托管）。块输入框中的 credentials 字段声明的是「用户自己的 Ayrshare profile key」，并非管理员密钥。它由 AyrshareManagedProvider 托管：用户首次从块触发 SSO 流程时，系统在 Ayrshare 侧创建标题带随机后缀（避免与孤儿 profile 冲突）的 User Profile 并把返回的 profileKey 以 is_managed=True 的 APIKeyCredentials 形式存入用户凭据列表。该 Provider 刻意将 auto_provision = False，因为每个 profile 都占用组织订阅配额，仅在用户显式操作时开通。deprovision 则不做任何事——Ayrshare 未开放编程式删除 profile 的端点，清理需在 Ayrshare 后台手工完成。

3. 社交渠道 OAuth 关联。注意：profile 被创建 ≠ YouTube 账号已关联。用户仍须在 Builder 弹出的 Ayrshare SSO 页面里完成 YouTube 的 OAuth 授权；在此之前，块会把 Ayrshare API 返回的 "xxx is not linked" 类错误原样抛出（参见 ayrshare.py 对 posts[].errors[].message 的解析逻辑）。只有同时满足三个条件，块才能发布成功：AYRSHARE_API_KEY/AYRSHARE_JWT_KEY 已配置、用户 profile 凭据存在且被选中、该 profile 已关联 YouTube。

请求发出时，create_post() 会把 profile key 放入 Profile-Key 请求头并调用 POST https://api.ayrshare.com/api/post（ayrshare.py），响应即使 HTTP 状态码非 200 也交由统一错误抽取函数 _extract_error_message 处理，最终以带 status_code 的 AyrshareAPIException 形式向上传递。

三、输入参数全解

块的全部输入定义在 post_to_youtube.py 的 Input 类。其中 title、visibility 及下方的 YouTube 专属字段在子类中新增/覆写，其余字段继承自 BaseAyrshareInput。以下表格完整收录官方文档中的全部字段：

输入	说明	类型	必填
post	视频描述（最多 5000 字符，允许空串），不得包含 < 或 > 字符	str	是
media_urls	必传的视频 URL，YouTube 每帖仅支持 1 个视频	List[str]	否*
is_video	是否视频媒体（对 YouTube 恒为 True）	bool	否
schedule_date	调度 UTC 时间（YYYY-MM-DDThh:mm:ssZ）	str (date-time)	否
disable_comments	是否关闭评论	bool	否
shorten_links	是否缩短链接	bool	否
unsplash	Unsplash 图片配置	str	否
requires_approval	是否启用审批工作流	bool	否
random_post	是否生成随机帖文	bool	否
random_media_url	是否随机生成媒体	bool	否
notes	帖子的附加备注	str	否
title	视频标题（最多 100 字符，必填），不得包含 < 或 > 字符	str	是
visibility	可见性：private（默认）、public、unlisted	"private" | "public" | "unlisted"	否
thumbnail	缩略图 URL（JPEG/PNG，小于 2MB，必须以 .png/.jpg/.jpeg 结尾），需要电话验证	str	否
playlist_id	视频加入的播放列表 ID（用户须拥有该列表）	str	否
tags	视频标签（单个至少 2 字符，总长最多 500 字符）	List[str]	否
made_for_kids	自行声明为儿童向内容	bool	否
is_shorts	以 YouTube Short 形式发布（最长 3 分钟，自动追加 #shorts）	bool	否
notify_subscribers	是否向订阅者发送通知	bool	否
category_id	视频分类 ID（例如 24 = 娱乐）	int	否
contains_synthetic_media	声明内容含写实 AI/合成媒体	bool	否
publish_at	UTC 发布时刻（由 YouTube 控制，格式 2022-10-08T21:18:36Z）	str	否
targeting_block_countries	屏蔽观看的国家/地区代码（如 ['US', 'CA']）	List[str]	否
targeting_allow_countries	仅允许观看的国家/地区代码（如 ['GB', 'AU']）	List[str]	否
subtitle_url	SRT/SBV 字幕文件 URL（须 HTTPS 且以 .srt/.sbv 结尾，小于 100MB）	str	否
subtitle_language	字幕语言代码（默认 'en'）	str	否
subtitle_name	字幕轨道名称（最多 150 字符，默认 'English'）	str	否

* 注：schema 层面 media_urls 标记为可选，但运行时强制要求恰好 1 个视频 URL（见下节校验逻辑），因为 YouTube 只接受视频内容。

分组导读：如何正确填写

• 必填核心三件套：post（描述）、title（标题）、media_urls（恰好一个视频 URL）。源码 run() 对三者的缺失均会中止并输出对应 error，因此不要把三者放到高级设置之外的可空位置。
• 内容合规：标题 ≤100 字符、描述 ≤5000 字符、</> 一律禁止，违反任何一条都会被块内直接拒绝，不会消耗网络请求。
• 可见性与受众：默认 private 意味着调试期视频不会公开；正式发布前请显式改为 public 或 unlisted。notify_subscribers 默认行为是跟随订阅通知——源码里只有显式传 False 时才设置 notifySubscribers: false（L269-L270），即块默认不会去额外打开订阅者通知。
• 排期二选一：schedule_date（Ayrshare 调度）与 publish_at（YouTube 原生调度）不可同时使用，代码会在检测到二者并存时直接报错（L238-L240）。schedule_date 传入后，代码先将其 datetime 格式化为 ISO 字符串再交给 Ayrshare。
• 竖版/横版无关的 Shorts 开关：is_shorts 会追加 #shorts 并走 Short 展示，注意其时长上限 3 分钟；这是纯参数声明，超出时长的视频仍会在 YouTube 侧被平台处理。

四、输出结构解析

块输出定义在 Output 类，运行时最多产出以下三个输出流：

输出	说明	类型
error	操作失败时的错误消息	str
post_result	本次发布请求的整体结果	PostResponse
post	每个平台维度的发布结果	PostIds

对应到客户端模型（ayrshare.py）：

• PostResponse：包含 status、id、refId、profileTitle、post（帖文原文）、postIds（数组）、scheduleDate、errors。Ayrshare 对单个发布请求也返回数组形式，客户端只取数组首元素做响应。
• PostIds：单个平台的发布明细，含 status、id、postUrl、platform。因此在 Creator 端你可以用后续块读取 postUrl 做 URL 存档、通知或数据分析。

run() 的产出方式（L313-L316）：先产出一次完整 post_result，再遍历 response.postIds 逐条产出 post。也就是说下游若需要"每平台一条记录"，应挂在 post 输出上；需要"整单结果含错误与调度时间"，则读 post_result。

五、内置校验与错误信息（源码级）

块在调用网络前内置了完整的 YouTube 约束校验，这是比基础 Ayrshare 块更严格的差异点。每条校验失败都会 yield 对应 error 并提前 return（post_to_youtube.py）：

1. 未配置集成 → Ayrshare integration is not configured...；
2. 标题为空 / 超过 100 字符 → 报长度上限错误；
3. 描述超过 5000 字符 → 报长度上限错误；
4. 标题或描述含 < 或 > → 报字符禁用错误；
5. media_urls 为空或超过 1 个 → 分别报 YouTube requires exactly one video URL / YouTube supports only 1 video per post；
6. visibility 不在 private|public|unlisted 内 → 报枚举错误；
7. thumbnail 已提供但后缀不是 .png/.jpg/.jpeg → 报格式错误（注意：大小 2MB 与电话验证由 YouTube/Ayrshare 侧约束，块内仅做扩展名校验，lower() 比较大小写不敏感）；
8. tags 总长超过 500 字符、或任一标签短于 2 字符 → 分别报错；
9. subtitle_url 非 https:// 开头或不以 .srt/.sbv 结尾 → 报错；subtitle_name 超过 150 字符 → 报错；
10. publish_at 与 schedule_date 并存 → 报二选一错误。

这套"先本地校验、再上行网络"的设计，使绝大多数配置错误发生在毫秒级且可读的错误输出中，便于在工作流里接入重试、分支或人工通知。

六、字段映射：输入 → Ayrshare API（youtubeOptions）

块把输入整理为嵌套对象 youtube_options 后，作为 youTubeOptions 字段传给 create_post（post_to_youtube.py L247-L311，客户端在 ayrshare.py L502-L503 写入 payload）。掌握这张映射表，有助于排查"为什么 Ayrshare 后台看到的选项不对"：

块输入字段	发送到 Ayrshare 的键	触发条件
title	title	恒发送
visibility	visibility	仅当非 private 时（private 为服务端默认值）
thumbnail	thumbNail	提供时
playlist_id	playListId	提供时
tags	tags	提供时
made_for_kids	madeForKids: true	为真时
is_shorts	shorts: true	为真时
notify_subscribers	notifySubscribers: false	显式传 False 时
category_id	categoryId	提供且 > 0 时
contains_synthetic_media	containsSyntheticMedia: true	为真时
publish_at	publishAt	提供时
targeting_block_countries	targeting.block	提供时
targeting_allow_countries	targeting.allow	提供时
subtitle_url / subtitle_language / subtitle_name	subTitleUrl / subTitleLanguage / subTitleName	提供 subtitle_url 时（语言/名称缺省值由服务端兜底为 en / English）

与此同时，create_post() 的顶层参数会承载通用字段：platforms=[SocialPlatform.YOUTUBE]、mediaUrls、isVideo=True（YouTube 只支持视频，故恒为 True）、scheduleDate（已转 ISO）、disableComments、shortenLinks、unsplash、requiresApproval、randomPost、randomMediaUrl、notes，并携带 Profile-Key 头。整体负载结构为：

{
  "post": "视频描述……",
  "platforms": ["youtube"],
  "mediaUrls": ["https://example.com/video.mp4"],
  "isVideo": true,
  "scheduleDate": "2026-09-10T08:00:00Z",
  "youTubeOptions": {
    "title": "示例视频标题",
    "visibility": "public",
    "categoryId": 24,
    "tags": ["autogpt", "tutorial"],
    "shorts": true
  }
}

七、计费与成本：为什么 is_video 恒为 True

Ayrshare 按帖计费由 _cost.py 定义：cost_filter 依据输入时的 is_video 在 run() 执行前匹配费率——视频帖 5 credits、图片/文字帖 2 credits，匹配顺序按元组先后（视频档在前）。由于 YouTube 是纯视频平台，本块把基类 is_video 的默认值从 False 覆写为 True（L46-L52），从而保证发布 YouTube 永远命中 5-credit 视频档，避免"用户忘记打开开关导致费率档位错配"。这一点对于在成本监控面板上核对用量尤为关键。

八、典型编排场景

官方文档预留了 use case 占位，从源码能力可推断出以下落地场景（供你在 Builder 中参考连线）：

1. 内容工厂自动排期：定时块/LLM 内容块产出标题与描述 → 生成或检索视频 URL → Post To YouTube 以 visibility=public、schedule_date 未来时间运行 → 用 post 输出的 postUrl 归档到数据库。每日脚本化发布无需人工干预。
2. 多渠道分发一致性：将同一 post 与 media_urls 同时连到 PostToTikTokBlock 等其它 Ayrshare 块，实现一次生成、多平台投递，注意其它平台的字段约束不同（例如 YouTube 标题必填、单视频限制是 YouTube 特有）。
3. 失败可观测：将 error 输出接 LLM 块做错误摘要或接通知块；将 post_result.errors 中 Ayrshare 侧的逐平台错误（如"YouTube 未关联"）用于引导用户完成 SSO 授权。
4. 合规发布：made_for_kids、contains_synthetic_media、targeting_block_countries 组合使用，保证面向儿童/特定地区的发布符合平台披露与地域要求。
5. 字幕增强：先由转写块产出 SRT，存为 HTTPS 可访问 URL 后喂给 subtitle_url + subtitle_language，形成"自动转写 → 自动字幕"闭环。

九、相关源码与进一步阅读

若要深入理解块的行为与调试问题，可按下列路径继续研读：

• 块实现与校验： post_to_youtube.py
• 共享基类与目标结构： _util.py
• 费率档位： _cost.py
• Provider 凭据说明与注册： _config.py
• HTTP 客户端、错误抽取与响应模型： integrations/ayrshare.py
• 托管凭据供给与旧数据迁移： managed_providers/ayrshare.py 及对应测试 managed_providers/ayrshare_test.py
• 块族 ID 登记： ayrshare/init.py

十、注意事项小结

• 视频上传后是否立即可见取决于 visibility 与上传完成时长；private 只代表"列出范围"，不代表不消耗配额。
• thumbnail 与字幕 URL 必须是公网可访问的 HTTPS 资源（Ayrshare 服务端会主动抓取），内网或本地回环地址无法使用。
• 与 publish_at 不同，schedule_date 由 Ayrshare 调度队列控制；若你需要 YouTube 原生"排期发布"的严格语义，请使用前者并避免同时填写两者。
• 订阅费用属于组织 Ayrshare 套餐（仓库注释提及订阅代理模式），块内按帖消耗的 credits 面向单次运行计费；profile 数量的增长不产生运行时成本，但会占用订阅配额，废弃 profile 需在 Ayrshare 后台手动清理。