API 集成

用 Zapier 生成营销素材

新建营销记录后发起海报或视频任务，记下进度，拿到成品再交付。

约 3 分钟API 接入

下方提示词和代码保留原文。复制后，把示例中的占位值换成自己的资料。

本页目录

开始前 1. 建立 API 凭据连接 2. 先确认模板的字段 3. 在第一个 Zap 里提交 4. 另用一个 Zap 查状态 5. 文件就绪后再交给 Buffer 设置上限，避免误重复

开始前

准备已保存的模板和完整输入。源记录可以包含模板 ID、inputs、配文和唯一业务事件 ID，这些是你自己建的字段。你还需要 API by Zapier 权限，以及「设置 → API 密钥」中的个人密钥。API by Zapier 目前是付费测试功能，优先用它的连接凭据存密钥。

1. 建立 API 凭据连接

在 Zapier Apps 里添加 API by Zapier 连接：

示例

Authentication type: Static Headers (API key)
Header name: Authorization
Header value: Bearer YOUR_AGENTOS_KEY
Domain filter: api.bsquarerealty.com
Test URL:
https://api.bsquarerealty.com/v1/workflow-api/media/templates?medium=poster&limit=1

只在连接表单里填真实密钥。API 请求复用这个连接，不再把密钥复制到步骤里。

2. 先确认模板的字段

用 GET /v1/workflow-api/media/templates?medium=poster 列出模板，再用 GET /v1/workflow-api/media/templates/TEMPLATE_ID?medium=poster 读取所选模板。根据 body.inputSchema 把必填值从已批准的源记录映射过去。

视频的两次读取都改用 medium=video。解说视频需要写好的解说词和对应图片。「帮我做个视频」这样的文字不能代替必填值。需要整理请求体时，可把示例交给已连接的助手：

示例

Prepare, but do not execute, an AgentOS media API request for template [TEMPLATE ID]. Read its current input schema. Map the following approved campaign fields to its real input names: [FIELDS AND VALUES]. Return valid JSON with action, medium, templateId, inputs, and requestKey. List anything missing. Do not invent asset IDs, listing facts, or narration. Do not include an API key.

3. 在第一个 Zap 里提交

配置来源触发器，再添加 API by Zapier 的 API Request：

示例

Method: POST
URL: https://api.bsquarerealty.com/v1/workflow-api/media/generate
Content-Type: application/json

请求体填真实模板和它要求的输入：

              JSON
            
{
  "action": "start",
  "medium": "video",
  "templateId": "VIDEO_TEMPLATE_ID",
  "inputs": {},
  "outputFormat": "mp4",
  "requestKey": "campaign-SOURCE_EVENT_ID-video-v1"
}

做海报时改用 medium: "poster"，不传 outputFormat。恢复同一次提交时沿用原键和请求体。将 operation.operationId、媒体类型、源事件 ID、请求键和当前状态存进任务表。HTTP 202 只表示受理。

4. 另用一个 Zap 查状态

视频制作可能比一次延时更久。可以设第二个定时 Zap，从任务表读待办记录并查询原任务：

示例

GET https://api.bsquarerealty.com/v1/workflow-api/media/operations/OPERATION_ID?medium=video

任务表要自己在 Zapier 或其他连接的应用里建。遇到 queued 或 running，留待下次查询。到 succeeded 时选实际视频或海报图片。把 failed、canceled 标出来处理。结果为 unknown 时，停止自动重提，调查原任务。

下游交付成功后记下结果 ID，之后跳过已完成行。如果发送超时，先确认原动作有没有成功。工作台的请求键不会替 Buffer 或邮件去重。

少量试用时，可以加 Delay、GET 和成功状态筛选。固定延时无法保证成品就绪，筛掉仍在运行的记录也不会自动安排下次查询。

5. 文件就绪后再交给 Buffer

Buffer 的 Zapier 连接接受图片或视频的直链。使用已批准的成品和稳定公开地址，选对频道，测试前看清动作会存草稿还是发布。用多个频道时，分别配置并核对。

工作台下载链接会过期。要排期发布，先把文件放到允许公开的存储。别为了让 URL 可用而公开客户资料或未批准的素材。

相关资料：Buffer 的 Zapier 接入指南

设置上限，避免误重复

账号当前每分钟最多提交 5 次、每 24 小时 100 次，读取和审核每分钟 60 次。收到 429 时按 Retry-After 等待。共用同一密钥的 Zap 要错开提交和查询。测试 POST 会发起真实制作，测试 Buffer 可能产生真实写入。

指南依据工作台路由、请求格式以及 Zapier 和 Buffer 的官方文档编写，没有导入或端到端试跑。密钥接口没有单次渲染的回调参数，请查任务状态，别自行加 webhookUrl。