genviral

genviral Partner API 技能

TL;DR： 使用 @genviral/cli npm 包执行 60 多个 Partner API 命令；docs.genviral.io 是权威的 REST 参考文档（从 llms.txt 和 创建帖子 开始，了解 POST /posts 的载荷格式）。核心流程：get-pack → 分析图像（元数据 + 视觉）→ 使用 pinned_images 执行 generate → render → 视觉审核（硬性门槛）→ create-post → 记录到 workspace/performance/log.json。TikTok 文案流程：copy-tiktok-preview → copy-tiktok-import（pack_id 和 pack_images 必须且只能提供其中一项）。Studio AI：studio-models → studio-generate-image（同步）或 studio-generate-video → studio-video-status --poll（异步）。文件夹：create-folder → folder-items-add，用于整理文件和幻灯片。分析数据关联：将 analyticsId/id、platformPostId 和 genviralPostId 视为不同的标识符；使用 genviralPostId 或 externalId 将分析数据行映射回已创建的帖子。通过 GENVIRAL_API_KEY 进行身份验证。配置位于 defaults.yaml。实例数据位于 workspace/。

此技能的功能

• 多平台发帖： 在 TikTok、Instagram、YouTube、Pinterest、LinkedIn、Facebook、X 和 Bluesky 发布视频、幻灯片或纯文本帖子（通过 GET /accounts 查看各账号的 capabilities）
• Studio AI 生成： 通过 API 使用 AI 模型生成图像（同步）和视频（异步）
• 文件管理： 将视频/图像上传到 genviral 的 CDN；使用文件夹整理
• 文件夹管理： 为上传内容、AI 图像、AI 视频和幻灯片创建嵌套文件夹
• AI 幻灯片生成： 根据提示词创建照片轮播，并渲染为图像
• 模板系统： 创建可复用的幻灯片结构，将表现出色的内容转换为模板
• 素材包管理： 将图像素材包用作幻灯片背景
• 分析： KPI、帖子级指标、受追踪账号、刷新触发器
• 细分领域情报： 一次调用即可进行趋势研究（trend-brief），获取话题标签、声音、创作者、发布时段和开场角度
• 内容流水线： 从提示词到发布内容的完整自动化
• 表现追踪： 帖子日志、开场追踪、每周回顾
• 开场库： 维护并扩展经验证有效的内容开场库

工作原理

1. 生成或上传媒体
2. 创建面向一个或多个账号的帖子
3. 安排发布时间或发布（对于 TikTok 幻灯片，可选择保存为草稿，以便在发布前添加热门音频——要获得最佳效果，选择音乐需要人工判断）
4. 通过分析追踪表现
5. 学习并优化

重要的分析数据标识规则：

• analyticsId 是分析数据行的 ID（id 是同一值的旧版别名）
• platformPostId 是平台原生的帖子/视频 ID
• 如果关联成功，genviralPostId 是源 Genviral 帖子的 ID
• 如果存在，externalId 是源 Partner API external_id
• 对于 BYO TikTok MEDIA_UPLOAD，草稿/收件箱中的 publish_id 并非最终公开的 TikTok 视频 ID。只有在用户实际于 TikTok 发布后，近期尚未关联的草稿才会尽力进行关联，因此较早的数据行仍可能显示 genviralPostId / externalId 为 null。

所有配置均位于 defaults.yaml。机密信息通过环境变量提供。通过此技能发布的所有内容都会显示在 Genviral 控制面板中。

首次设置

如果是全新安装，请阅读 docs/setup.md，并通过对话引导用户完成入门设置：

1. 设置 API 密钥并验证其是否有效
2. 列出账号并选择要发布到哪些账号
3. 讨论图像策略（现有素材包、创建新素材包、每次发布时生成，或混合使用）
4. 可选择一起设置产品背景和品牌语气

不要使用硬编码的默认值。询问用户的偏好并据此调整。通过此技能执行的所有操作都会显示在 Genviral 控制面板中，因此用户始终拥有完整的可见性和控制权。

文件结构

genviral/
  SKILL.md                  # This file (kernel + routing)
  README.md                 # Human-facing overview
  defaults.yaml             # API config and defaults

  docs/
    setup.md                # Onboarding guide (conversational, 5 phases)
    api/
      accounts-files.md     # accounts, upload, list-files
      folders.md            # folder CRUD, move, ancestors, items management
      posts.md              # create-post, update-post, retry, list, get, delete
      slideshows.md         # generate/render/update + TikTok copy preview/import + text styles
      packs.md              # pack CRUD + smart image selection (MANDATORY reading for any pack workflow)
      templates.md          # template CRUD + create-from-slideshow
      analytics.md          # all analytics commands
      studio.md             # Studio AI: generate images/videos, list models, poll status
      subscription.md       # subscription status, credits, tier
      pipeline.md           # content pipeline, performance loop, CTA testing, platform tips
      errors.md             # error codes and troubleshooting
    references/
      analytics-loop.md     # Full analytics feedback loop and weekly review process
      competitor-research.md # How to research competitors
    prompts/
      slideshow.md          # Prompt templates for slideshow generation
      hooks.md              # Prompt templates for hook brainstorming

  workspace/                # All instance/customer data (override with GENVIRAL_WORKSPACE_DIR)
    content/
      scratchpad.md         # Working content plan and drafts
      calendar.json         # Upcoming planned posts
    context/
      product.md            # Product description, value props, target audience
      brand-voice.md        # Tone, style, do's and don'ts
      niche-research.md     # Platform research for the niche
    hooks/
      library.json          # Hook instances (grows over time, tracks performance)
      formulas.md           # Hook formula patterns and psychology
    performance/
      log.json              # CANONICAL post record (single source of truth)
      hook-tracker.json     # Hook and CTA tracking with metrics (the feedback loop)
      insights.md           # Agent learnings from performance data
      weekly-review.md      # Weekly review notes
      competitor-insights.md # Competitor research findings

  scripts/
    genviral.sh               # Optional wrapper that delegates to the npm CLI and sets GENVIRAL_CONFIG
    update-skill.sh           # Self-updater

命令路由

仅加载当前任务所需的内容：

任务	阅读
原始 POST /posts JSON、服务商设置、幂等性、排期规则	docs.genviral.io/llms.txt + 创建帖子（不要在技能文档中重复完整规范）
账号发现、文件上传	docs/api/accounts-files.md
文件夹管理（创建、列出、移动、删除、项目）	docs/api/folders.md
影响者 / 一致性角色	docs/api/influencers.md
创建、更新、列出、删除帖子	docs/api/posts.md
幻灯片生成、TikTok 文案导入、渲染、编辑、文本样式	docs/api/slideshows.md
素材包管理、图片选择（任何素材包工作流）	docs/api/packs.md
模板创建与管理	docs/api/templates.md
分析查询与目标管理	docs/api/analytics.md
Studio AI：生成图片、视频、列出模型	docs/api/studio.md
订阅：检查额度、层级、续订日期	docs/api/subscription.md
快速研究特定细分领域（趋势 + 竞争对手 + 开场钩子）	docs/api/analytics.md、docs/references/competitor-research.md、docs/prompts/hooks.md
完整内容流程、效果循环、CTA 测试	docs/api/pipeline.md
错误代码、故障排查	docs/api/errors.md

细分领域研究模式（用户要求研究某个细分领域时）

当用户提出“研究这个细分领域”“找出这个领域里哪些内容有效”或“给我一些细分领域情报”等请求时：

1. 首先针对该细分领域的关键词运行 trend-brief（先使用 7d 基线；如需了解最新情况，再使用 24h）。
2. 提取并报告：热门话题标签、热门音频、热门创作者、发布时段（UTC）、推荐的开场钩子角度。
3. 使用 docs/references/competitor-research.md 深入研究竞争对手（至少 3-5 个账号）。
4. 生成简短且可执行的输出，包括：
   • 3 个待测试的开场钩子角度
   • 2 条 CTA 建议
   • 2 个最佳发布时间段
   • 5 个起步话题标签
   • 1 条“可利用的空白”洞察
5. 将研究结果保存到 workspace/performance/competitor-insights.md，并在后续内容提示词中使用。

TikTok 文案改编模式（用户要求“制作类似但全新的内容”时）

当用户想复制 TikTok 幻灯片创意但生成新的视觉内容时：

1. 首先运行 copy-tiktok-preview，并记录 preview_id、源图片 URL 和幻灯片数量。
2. 运行 copy-tiktok-import，并且只使用一个素材包来源（pack_id 或 pack_images），以便提取文本叠加层并将其映射到可编辑幻灯片。
3. 使用 Studio 和 google/nano-banana-2，将每张源幻灯片图片作为参考输入，生成替换图片：
   • 命令：studio-generate-image --model-id "google/nano-banana-2" --image-urls "<source_url>" --prompt "<product-aware transformation prompt>"
4. 根据 workspace/context/product.md 中的产品背景编写提示词，确保生成的视觉内容与广告宣传的产品相关。
5. 使用生成的 URL 替换幻灯片背景（update --slides-file ...），同时保留或编辑导入的文本元素。
6. 发布前先渲染（render）并检查（review）；绝不能跳过视觉质量检查。

分析数据关联模式（用户要求“将分析数据对应回帖子”时）

1. 获取 analytics-posts --json。
2. 优先使用 genviralPostId 将分析数据行与 Genviral 帖子进行匹配。
3. 如果需要调用方自己的稳定 ID，请使用 externalId。
4. 仅将 analyticsId / 旧版 id 视为分析数据行标识符。
5. 仅将 platformPostId 视为 TikTok/Instagram/YouTube 平台原生帖子标识符。
6. 对于 BYO TikTok 草稿（MEDIA_UPLOAD），不要假定草稿上传后立即能建立关联。只有用户从 TikTok 发布视频，且 Genviral 将其解析为最终公开的 TikTok 视频 ID 后，草稿的 publish_id 才能用于匹配。

规范 API 参考

日常自动化请使用 CLI。对于 REST 请求载荷、验证规则和提供商专属字段，请将 docs.genviral.io 与 CLI 一起视为权威来源：

1. llms.txt — 面向 Agent 的完整文档索引（优先使用此索引，而不是将端点列表复制到提示词中）。
2. 创建帖子 — POST /api/partner/v1/posts 请求体：caption、accounts、media、scheduled_at、external_id、music_url 和提供商设置。

不要在技能文件中粘贴或维护完整的 Partner API 规范。在此处概述工作流；构建或调试请求时，请从上述文档中获取字段结构。

发布请求载荷提示（表格和限制请参见创建帖子）：

• 首先调用 GET /accounts；使用每个账号的 capabilities（supported_content_kinds、caption_limit）。capabilities.settings_schema 反映的是控制台中的编辑器，字段名可能与 Partner API 不同。
• 创建时，TikTok 和 Pinterest 设置是顶层的 tiktok 和 pinterest，而非 settings.tiktok / settings.pinterest。
• 其他平台使用 settings.<provider>（例如 settings.youtube、settings.x、settings.instagram 或 settings.instagram-standalone、settings.bluesky）。
• 仅当所有选定账号都支持 text_only 时，才省略 media。
• music_url 仅适用于 TikTok（如果选定了任何非 TikTok 账号，则会被拒绝）。
• scheduled_at 必须是带时区偏移量的 ISO 8601 格式；实际定时发布时间必须至少在未来 2 分钟。
• 幂等性优先使用 external_id（最多 128 个字符）；相同键和相同请求载荷重放时会返回 duplicate: true。

不可妥协的规则

无论加载了哪些文档，以下规则始终适用：

1. 生成带素材包的幻灯片时，始终使用 pinned_images。绝不要只用 --pack-id 调用 generate，否则服务器会随机选择图片。进行任何素材包工作流前，请先阅读 docs/api/packs.md。

2. 发布前始终逐张目视检查每一张渲染后的幻灯片。如果有任何一张难以阅读，就修复它。这是硬性要求，不是建议。

3. 发布后立即始终记录到 workspace/performance/log.json。这是规范记录。

4. 发布后始终添加一条 hook-tracker 记录。没有追踪就没有学习。

5. 生成的任何内容中都不得使用 em-dash。

6. 遵守 workspace/ 规则：所有实例数据都存放在此处。不要将状态文件写入技能根目录。

CLI 安装

全局安装一次 Partner API CLI：

npm install -g @genviral/cli

npm 包会发布 genviral 和 genviral-cli。在说明和自动化中优先使用 genviral 二进制文件。

从 monorepo 本地安装（npm 发布前）：

pnpm --filter @genviral/partner-api-contracts pack --pack-destination /tmp
pnpm --filter @genviral/cli pack --pack-destination /tmp
npm install -g /tmp/genviral-partner-api-contracts-0.1.0.tgz /tmp/genviral-cli-0.1.0.tgz

此技能的 scripts/genviral.sh 只是一个便捷封装脚本。它会转发到 npm 的 genviral 二进制文件，并在尚未设置 GENVIRAL_CONFIG 时将其设为此技能的 defaults.yaml。不要将它作为 Partner API 命令的独立 shell 实现来记录或依赖。

CLI 用法

genviral <command> [options]
# or from the skill directory:
./scripts/genviral.sh <command> [options]

需要将 GENVIRAL_API_KEY 设为环境变量（格式：public_id.secret）。CLI 从 --config 或 GENVIRAL_CONFIG 加载默认值；对于本地技能运行，技能封装脚本会将 GENVIRAL_CONFIG 指向 defaults.yaml。设置 GENVIRAL_WORKSPACE_DIR 可覆盖工作区路径（默认相对于技能目录的 workspace/）。

自动更新

此技能包含一个自更新程序，可将技能自有文件与 fdarkaou/genviral-skill 的最新版本保持同步。

bash scripts/update-skill.sh           # check + apply if updates available
bash scripts/update-skill.sh --dry-run # preview only, no changes
bash scripts/update-skill.sh --force   # force re-apply even if already current

会更新的内容（技能自有）： README.md、SKILL.md、scripts/、docs/（所有子目录）

不会触碰的内容（用户自有）： workspace/，你的数据、上下文、钩子和性能日志始终会得到保留。

---

注意事项

• 合作伙伴 API 基础 URL：https://www.genviral.io/api/partner/v1（参见简介）
• 发布平台：TikTok、Instagram、YouTube、Facebook、Pinterest、LinkedIn、X、Bluesky（仅支持 TikTok、Instagram、YouTube 数据分析）
• 支持视频、幻灯片和纯文本帖子（取决于账号的 capabilities）
• 支持托管账号和 BYO 账号；创建时，TikTok 专属设置要求使用 BYO TikTok
• 帖子可以定时发布，也可以加入队列立即发布
• TikTok 幻灯片草稿：使用顶层 tiktok.post_mode: MEDIA_UPLOAD 将内容保存到草稿收件箱，以便添加音频
• BYO TikTok 草稿上传（MEDIA_UPLOAD）会立即创建 Genviral 帖子，但只有用户在 TikTok 中发布后，才会生成最终的公开 TikTok 视频 ID。在 analytics-posts 中，使用 genviralPostId 或 externalId 进行关联；将 analyticsId/旧版 id 视为数据分析行 ID，将 platformPostId 视为 TikTok 原生 ID。

Meta Ads 配套指南（已包含）

此代码库在 meta-ads/ 目录中包含 meta-ads 配套指南——一个自主的 Meta（Facebook/Instagram）Ads 管理器和 8 阶段 AI 广告系列构建器，使用 Genviral 的 Studio API 生成广告创意。

请参阅 meta-ads/INSTRUCTIONS.md，了解随附的工作流和设置指南。

也可单独获取：fdarkaou/meta-ads-skill