基于 Ayrshare 的 AutoGPT TikTok 发布块：从图文/视频发布到 AI 披露与合规配置指南

AutoGPT Platform 通过 Ayrshare 社交媒体管理 API 提供了面向 TikTok 的发布块（Post To TikTok），让 Agent 工作流可以直接发布单条视频或最多 35 张图片组成的幻灯片帖，并原生支持 AI 生成内容披露、品牌合作标签、可见性与互动权限控制、草稿与定时发布等能力。本文以关联文档 post_to_tiktok.md 为核心，结合仓库中的块实现源码、Ayrshare 客户端封装与计费配置，逐项讲解该块的输入输出、媒体格式约束、选项组合逻辑、计费规则与典型应用场景，读完即可在 AutoGPT 构建器中配置出一个合规、可排期、可落地的 TikTok 内容发布流程。

一、模块定位：TikTok 发布块在 AutoGPT 中的角色

PostToTikTokBlock 是 AutoGPT Platform 中用于"把内容发到 TikTok"的社交发布块。它的完整实现在 post_to_tiktok.py，块的唯一标识（id）为 7faf4b27-96b0-4f05-bf64-e0de54ae74e1，分类为 SOCIAL（社交媒体），块类型为 AYRSHARE，即整条链路经由 Ayrshare 的 API 代理完成，而非直接对接 TikTok 官方接口。

从目录结构看，该块只是 Ayrshare 集成块家族的一员。仓库 autogpt_platform/backend/backend/blocks/ayrshare/ 下同时存在面向 Instagram、Facebook、X、LinkedIn、YouTube、Reddit、Telegram、Snapchat、Threads、Pinterest、Bluesky、Google My Business 的同类发布块，且在 init.py 中以 AYRSHARE_BLOCK_IDS 统一登记了各块 ID。这意味着：如果你已经在同一套 AutoGPT 平台中为其他社交平台配置过 Ayrshare，那么连接 TikTok 账号与配置密钥的机制是完全一致的，学习成本可以复用。

二、工作原理：Ayrshare 代理层 + TikTok 专属选项透传

2.1 调用链概览

块的运行逻辑在 run() 中，整体是一条"校验 → 组装选项 → 调用 Ayrshare API → 产出结果"的链路：

1. 通过 create_ayrshare_client() 创建 Ayrshare 客户端；若后端未配置 AYRSHARE_API_KEY，客户端返回 None，块直接产出 error 输出。
2. 对帖子文本长度、媒体 URL 数量、视频/图片格式组合等做 TikTok 特有的前置校验。
3. 将布尔开关与数值选项按视频/图片类别映射成 TikTok 专属的 tiktok_options 字典（键名为 Ayrshare API 的 camelCase 风格）。
4. 调用 AyrshareClient.create_post(...)，平台固定为 SocialPlatform.TIKTOK，同时携带账号凭据 profile_key。
5. 把完整的 PostResponse 通过 post_result 输出，并把响应中每个平台的帖子 ID 逐个通过 post 输出。

2.2 客户端与凭据如何工作

客户端实现位于 ayrshare.py。AyrshareClient.__init__ 从后端设置中读取 settings.secrets.ayrshare_api_key，若缺失则抛出 MissingConfigError（即"未配置"分支）；请求以 Authorization: Bearer <api_key> 形式发往 https://api.ayrshare.com/api/post。

账号层有一个重要的设计：在 _util.py 的基类输入中，credentials 字段描述说明——Ayrshare profile credential 是由 AutoGPT 平台自动托管的托管凭据（managed credential），用户不需要自己创建。凭据就绪后，用户只需在构建器中通过 Ayrshare 的 SSO 弹窗把各个社交账号（包括 TikTok）关联到该凭据即可。因此，在编排流程时你只需要正确选择/引用这个 Ayrshare profile credential，而账号授权是在平台侧一次性完成的。

2.3 选项如何进入 API 请求

create_post 的完整签名见 ayrshare.py，TikTok 专属配置通过 tiktok_options: Optional[dict] 参数传入，最终被打包进请求体。块代码内部把 tiktok_options 中所有开关按需置 True，例如：

• disable_comments → disableComments
• is_branded_content → isBrandedContent
• is_brand_organic → isBrandOrganic
• disable_duet → disableDuet（仅视频）
• disable_stitch → disableStitch（仅视频）
• is_ai_generated → isAIGenerated（仅视频）
• thumbnail_offset → thumbNailOffset（仅视频）
• draft → draft（仅视频）
• image_cover_index → imageCoverIndex（仅图片）
• title → title（仅图片）
• visibility → visibility（仅图片）

三、输入参数详解

下表完整覆盖了块的输入 Schema（对应 post_to_tiktok.py 中 Input 的定义）。除文档给出的约束外，表中补充了从源码可确认的默认值、是否属于"高级选项"（advanced）以及影响范围，方便你在构建器表单中快速定位。

输入	说明	类型	必填	默认值/补充说明（源码确认）
post	帖子文本（最多 2,200 字符，允许空字符串）。用 @handle 提及用户，换行会被忽略	str	是	默认 ""，基础选项；超过 2,200 字符会在运行期报错
media_urls	必填媒体 URL。只能是 1 个视频，或最多 35 张图片（仅 JPG/JPEG/WEBP）。视频与图片不可混用	List[str]	否	默认空列表；为空时运行期报错，因为 TikTok 不允许纯文本帖子
is_video	媒体是否为视频。上传视频时设为 True，使计费按视频档位收取	bool	否	默认 False，高级选项；与计费强相关（见下文"成本与计费"）
schedule_date	UTC 定时发布时间（格式 YYYY-MM-DDThh:mm:ssZ）	str (date-time)	否	源码中为 Optional[datetime]，传入后会经 .isoformat() 转成字符串再进 API
disable_comments	发布后禁用评论	bool	否	默认 False
shorten_links	是否缩短链接	bool	否	默认 False；作为通用 API 参数 shortenLinks 透传
unsplash	Unsplash 图片配置	str	否	默认 None，作为通用 API 参数透传
requires_approval	是否启用审批工作流	bool	否	默认 False，作为通用 API 参数透传
random_post	是否生成随机帖子文本	bool	否	默认 False，作为通用 API 参数透传
random_media_url	是否生成随机媒体	bool	否	默认 False，作为通用 API 参数透传
notes	帖子的附加备注	str	否	默认 None
auto_add_music	是否自动添加推荐音乐。设为 true 后仍可在 TikTok App 中更换音乐	bool	否	默认 False，高级选项；当前源码实现中仅在"图片帖子"且开启时才写入 autoAddMusic
disable_duet	禁止他人对已发布视频做合拍（Duet），仅视频有效	bool	否	默认 False
disable_stitch	禁止他人对已发布视频做剪接（Stitch），仅视频有效	bool	否	默认 False
is_ai_generated	AI 生成内容披露开关。开启后帖子会被标注为"Creator labeled as AI-generated"，且发布后不可修改；该标签表示内容完全由 AI 生成或经 AI 大幅编辑	bool	否	默认 False，仅视频场景生效
is_branded_content	品牌合作内容开关。开启后标注为 Branded Content（与品牌的付费合作），视频会附带 "Paid partnership" 标签	bool	否	默认 False
is_brand_organic	品牌自有内容开关。开启后标注为 Brand Organic Content（推广自己或自有业务），视频会附带 "Promotional content" 标签	bool	否	默认 False
image_cover_index	用作封面的图片下标（从 0 开始），仅图片帖子有效	int	否	默认 0；越界会在运行期报错
title	图片帖子的标题	str	否	默认 ""，仅图片帖子有效
thumbnail_offset	视频缩略图帧偏移（毫秒），仅视频有效	int	否	默认 0；只有大于 0 才会写入选项
visibility	帖子可见性：public / private / followers	"public" | "private" | "followers"	否	默认 public；当前实现中仅对图片帖子应用非 public 值（见下文第六节）
draft	是否创建为草稿（仅视频）	bool	否	默认 False，仅视频场景生效

需要留意字段名细节：块的输入说明中 visibility 的类型是三个可选枚举值 public / private / followers，对应源码中 TikTokVisibility 枚举（post_to_tiktok.py）定义的三档，而不是任意字符串。

四、媒体格式约束与运行期校验（源码级）

与文档"媒体 URL 约束"相呼应，块的 run() 在真正发请求前做了一整套校验。这些校验是可验证的事实行为，对设计工作流非常有参考价值：

1. 文本长度校验：post 超过 2,200 字符时，输出错误 "TikTok post text exceeds 2,200 character limit"。

2. 媒体非空校验：media_urls 为空时直接报错 "TikTok requires at least one media URL"——也就是说 TikTok 场景不允许只发纯文本（与文档输入表中"required media URLs"的措辞一致，虽然该字段在 Schema 上标记为非必填，但运行期强校验）。

3. 格式识别：通过扩展名判断媒体类型，源码白名单为：

• 视频扩展名：.mp4、.mov、.avi、.mkv、.wmv、.flv、.webm；
• 图片扩展名：.jpg、.jpeg、.webp。

同时 is_video 为 True 会被直接当作视频处理，因此 URL 不带扩展名时也可以靠该开关显式声明视频类型。

4. 组合约束：

• 视频与图片同时存在 → "TikTok does not support mixing video and images"；
• 视频多于 1 个 → "TikTok supports only 1 video per post"；
• 图片多于 35 张 → "TikTok supports a maximum of 35 images per post"；
• 含 .png → "TikTok does not support PNG files. Please use JPG, JPEG, or WEBP"（文档输入表未单独强调 PNG 被拒，这是源码中额外的硬约束，值得注意）；
• 图片场景下 image_cover_index >= 图片总数 → 越界错误。

5. 媒体类型判定还决定选项范围：has_video 或 has_images 的分支会决定哪些 TikTok 专属选项能真正生效（见第六节），因此流程设计阶段应尽量让被引用媒体 URL 的扩展名清晰明确。

五、输出结构解读

块的 Output 定义了两个业务输出（post_to_tiktok.py），加上贯穿所有块的 error，共有三个输出：

输出	类型	说明
error	str	运行失败时的错误信息（如未配置密钥、校验不通过、Ayrshare API 返回错误）
post_result	PostResponse	Ayrshare 返回的完整发帖结果
post	PostIds	单个平台粒度的发帖结果，每个帖子逐条输出

对应的模型定义见 ayrshare.py：

• PostResponse 包含 status、id、refId、profileTitle、post、postIds、scheduleDate、errors；
• PostIds 包含 status、id、postUrl、platform，其中 postUrl 可以直接作为"发布成功后的链接"继续喂给下游块（例如存入数据库或发送通知）。

run() 中，先 yield "post_result", response 输出整体响应；随后若 response.postIds 非空，则遍历并逐个 yield "post", p，这样下游既可以用 post_result 拿到聚合态结果（如排期时间），也可以用 post 精确拿到 TikTok 站内 id 与访问链接。

六、视频 vs 图片：专属选项的分流逻辑

这是理解本块行为的关键。源码把 TikTok 专属选项严格区分成三类（post_to_tiktok.py）：

通用选项（图文视频皆可）：disable_comments、is_branded_content、is_brand_organic。其中 disable_comments 除写入选项字典外，也会作为 create_post 的通用参数传递。

仅视频生效：disable_duet（禁止合拍）、disable_stitch（禁止剪接）、is_ai_generated（AI 披露标签）、thumbnail_offset > 0（缩略图帧偏移，毫秒）、draft（存为草稿）。

仅图片生效：auto_add_music（推荐音乐，视频自带音轨故仅用于图集）、image_cover_index > 0（指定封面图）、title 非空（图集标题）、visibility 非 public（可见性）。

有两个值得强调的"文档与源码存在微妙差异"的点，设计工作流时要按源码行为为准：

1. visibility 只作用于图片帖子：即便文档与字段描述都给出三档可见性，源码中只有 has_images 分支才会把非 public 的可见性写入 tiktok_options。
2. auto_add_music 只在图片帖子中生效：字段描述暗示的是通用行为，但实现里需要 auto_add_music and has_images 同时成立才写入 autoAddMusic。

从设计意图上推断：TikTok 视频天然携带音频，图片幻灯片才是"自动配乐"的目标场景；而视频的可见性一般由 draft、发布人账号设置或 TikTok App 内操作管理。若你的流程需要"视频仅自己可见/草稿评审后再发"，请显式打开 draft，配合 schedule_date 或人工审批节点完成发布。

七、典型应用场景

文档给出三类典型用法，这里结合块的参数组合做可落地的展开：

1. Creator Content Pipeline（创作者内容流水线） 面向批量发布视频的创作者，将 is_ai_generated=True 与视频参数组合使用：批量上传视频时自动带上 AI 生成披露标签、按需关闭 Duet/Stitch、必要时以 draft=True 先落草稿供人工复查，最后 schedule_date 定点放量。TikTok 对 AI 生成内容的披露标签在发布后不可更改，因此让披露开关成为流程中的固定输入而不是人工记忆，是规避合规风险的关键。

2. Brand Campaigns（品牌合作投放） 当视频背后存在品牌付费合作关系时，置 is_branded_content=True（视频带 "Paid partnership" 标签）；推广自身业务时置 is_brand_organic=True（带 "Promotional content" 标签）。文档明确强调这与 FTC 合规及平台准则相关，AutoGPT 流程把这些标签固化成参数，能保证每一条自动发布的内容都带正确披露，避免人工漏配。

3. Image Slideshow Posts（图片幻灯片帖子） 从产品图库或摄影图集中挑选不超过 35 张 JPG/JPEG/WEBP 图片组成幻灯片，用 image_cover_index 指定封面、title 填充图集标题、必要时开 auto_add_music 与 visibility。此场景尤其适合电商上新、活动预告等需要批量、周期性发布图集的内容运营。

八、成本与计费：视频档与图文档的差异

该块是带运行时计费的。计费配置在 _cost.py，AYRSHARE_POST_COSTS 定义了两档 RUN 类型的费用：

• is_video=True：每次运行扣 5 个信用点（credit）；
• is_video=False：每次运行扣 2 个信用点。

两个关键机制值得注意：

1. cost_filter 在 run() 执行前按输入匹配，且"先匹配先生效"。因此视频档必须排在前面，否则图文档会错误覆盖。源码注释也指出：对 TikTok 这类图文视频都支持的平台，计费是否正确取决于调用方是否在输入评估阶段就把 is_video 设对——这正是文档与输入表中反复强调"上传视频时把 is_video 设为 True"的原因：它不只是给 Ayrshare API 的类型提示，还直接决定计费档位。
2. 源码注释解释了该定价模型的背景：Ayrshare 本身是订阅制代理服务，按帖计费是为了防止单个重度用户独占固定订阅成本，并与不同帖子形态的上传成本对齐。

因此在构建流程时，请确保 is_video 始终与 media_urls 的真实类型一致，否则会出现"按图文档扣费却实际发视频"或反之的计费偏差。

九、在 AutoGPT 构建器中接入：配置步骤与排错要点

结合块输入、凭据机制与源码错误分支，完整的接入与排错建议如下：

1. 平台级前置条件 在 AutoGPT Platform 运行环境配置 Ayrshare API 密钥（对应源码读取的 AYRSHARE_API_KEY）。若缺失，create_ayrshare_client() 会返回 None（见 _util.py），块将输出错误："Ayrshare integration is not configured. Please set up the AYRSHARE_API_KEY."

2. 连接社交账号 块输入中引用 AutoGPT 自动托管的 Ayrshare profile credential，再通过构建器中的 Ayrshare SSO 弹窗把 TikTok 账号关联到该凭据（见 _util.py 的凭据字段说明）。

3. 配置核心输入

• post：正文（≤2,200 字符，空串允许）；
• media_urls：1 条视频或 ≤35 张 JPG/JPEG/WEBP 图片的 URL 列表，勿混用、勿含 PNG；
• is_video：按媒体类型如实设置（兼顾 Ayrshare 计费与 API 类型）；
• 需要时打开高级选项（advanced=True 的字段），例如定时（schedule_date）、合规标签（is_ai_generated / is_branded_content / is_brand_organic）、互动限制（disable_comments / disable_duet / disable_stitch）与草稿（draft）。

4. 常见失败分支速查（全部可在 post_to_tiktok.py 中核实）：

• 未配置 Ayrshare API Key → 前置错误；
• 文本超长 / 无媒体 / 视频图片混用 / 视频超 1 条 / 图片超 35 张 / 出现 PNG / 封面下标越界 → 各返回对应中文可读的 error 输出；
• Ayrshare API 层失败 → 客户端按 response.ok 与响应 status 信封抛出带 Ayrshare 原始错误信息的异常（见 ayrshare.py）。

5. 下游衔接建议 post_result.postIds[].postUrl 与逐条的 post 输出可接后续节点，用于"发布成功后记录链接/发通知/写数据库"，实现从生成内容 → 合规检查 → 定时发布 → 结果留痕的完整闭环。

结语

Post To TikTok 块把 TikTok 发布链路中最繁琐的部分——媒体格式约束、平台专属选项、合规披露标签、账号凭据与计费——收敛成一组清晰的输入输出。理解其底层实现（post_to_tiktok.py、ayrshare.py 与 _cost.py）能帮助你避开诸如"visibility 仅对图集生效""PNG 会被拒绝""is_video 决定计费档位"之类的隐性坑。建议在动手编排前，先在构建器里用一条真实 TikTok 草稿验证账号连通性与媒体 URL 可达性，再把参数固化到可复用的流程模板中。