HTTP API

通过现有 HTTP API 完成身份验证、发现工具并确认变更。

向可信的 Influence 源站（例如 https://influence.so）发送产品 API 请求。文档域名不接收产品 API 请求。请使用下列精确路径，不添加查询参数。

创建限定权限的 API 密钥

在 Influence 设置中，打开应用与自动化 → API 密钥。选择所需权限和有效期。密钥只展示1次，请将其存入机密存储，命名为 PUBLISH_API_TOKEN。通过 Authorization: Bearer … 发送密钥，切勿放入 URL、请求正文或聊天。无需使用时，请撤销密钥。

发现工具并读取账号

将 PUBLISH_API_URL 设为可信源站。以下示例假定进程已持有 PUBLISH_API_TOKEN。accountList 需要 integrations:read 权限；请按其分页字段继续获取后续页面。

export PUBLISH_API_URL="https://influence.so"
curl "$PUBLISH_API_URL/api/v1/tools" \
  -H "Authorization: Bearer $PUBLISH_API_TOKEN"

curl "$PUBLISH_API_URL/api/v1/tools/accountList/call" \
  -H "Authorization: Bearer $PUBLISH_API_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"input":{}}'

请求路径

方法	路径	用途
`GET`	`/api/v1/tools`	列出当前凭据可用的工具。
`POST`	`/api/v1/tools/{tool}/call`	调用无需确认的工具，包括已获授权的上传续传操作。
`POST`	`/api/v1/tools/{tool}/prepare`	准备精确的写入内容，不执行写入。
`POST`	`/api/v1/tools/{tool}/confirm`	确认已准备的写入。
`POST`	`/api/v1/media/import`	确认已准备的小型二进制图片上传。

JSON 工具请求使用 Content-Type: application/json，正文仅包含 input：{"input":{…}}。各工具的输入结构请从当前工具目录获取。

准备并确认操作

以目录中的 confirmation 字段为准：读取通常无需确认，但数据洞察刷新虽然属于读取，仍需确认。上传分片查询、完成和取消操作通过 /call 继续已获授权的上传。

将精确的业务输入发送至 /prepare。成功响应包含 status: "confirmation_required"、confirmationCapability、expiresAt、inputDigest，以及可选的 summary。
在过期前，将相同输入发送至 /confirm。在 X-Publish-Confirmation 中提供返回的确认凭据，并在 Idempotency-Key 中提供调用方新生成的幂等键。
将输入、确认凭据和幂等键保存在一起。如果确认过程被中断，或结果不确定，请为同一请求复用这3项值。不要为恢复不确定的结果重新准备替代请求。

幂等键包含16–200个字符，可用字符为 A–Z、a–z、0–9、.、_、: 和 -。确认凭据是不透明的机密值。向 /call 或 /prepare 发送幂等键，不会预留已确认的写入。

传输确认与发布批准是不同步骤。发布或更改定时安排前，请展示完整的当前审核内容：账号、文案、设置、实际素材预览或链接、定时发布时间及时区。对于符合条件的社交文字、图片和视频审核，客户端可通过 approval: "approved" 报告新的明确人工批准；不得编造同意，也不得把准备操作视为批准。Influence 将此记录为客户端报告的批准。受支持的嵌入式卡片或登录后的审核会记录各自的人工操作。

TikTok Direct 支持通过审核流程取得明确的聊天选择与同意。使用 campaignReview 保存完整选择，然后先取得对更新后审核内容的重新批准，再执行。审核卡片可选。普通 API/CLI 定时发布不消耗 AI 定时发布额度；单独的 MCP 与 Influence IQ 额度适用于这些流程，即使保存的 AI 审核稍后在 Influence 中获批，也按该额度计算。其他套餐与平台要求仍然适用。继续操作前，请读取已保存的回执；needs_review 要求核对并处理当前状态，不能再次发送。

处理错误与不确定的结果

同时检查 HTTP 状态和响应正文。工具成功时返回 {"ok":true,"toolName":"…","output":{…}}。工具失败时返回 {"ok":false,"toolName":"…","error":{"code":"…","message":"…","retryable":false}}，HTTP 状态仍可能为 200。传输失败使用 {"error":{"code":"…","message":"…","retryable":false}}，不含 ok 或 toolName。

401 表示需要身份验证，请检查凭据是否过期或已撤销。缺少权限时，需要取得相应授权，重复请求无济于事。503 可能表示服务不可用，或另一个定时发布请求正在更新工作区。请遵循返回的错误码与重试指引，不要自动重放发布操作。超时并不证明写入失败：请保留确认数据，并在重新提交前读取当前状态。已受理、已定时发布和已发布是不同结果。

上传素材

上传本地文件时，优先使用 SDK 的 uploadMedia 或 CLI 的 media:upload。它们使用相同的分片上传工具，并保留稳定的 clientKey 供重试。只有带 assetId 的就绪结果才能附加到内容中。对于已获授权的 HTTPS 链接，请使用 mediaImport，传入 url 和可选的 name。真实的宿主文件引用使用独立的 file 对象；公共 URL 不需要虚构的宿主文件 ID。本地文件路径不是下载 URL。请参阅素材限制：HTTPS 视频导入上限为 250 MiB，即使直接上传允许更大的就绪 MP4 文件，也受此限制。

POST /api/v1/media/import 支持现有的小图片传输方式：使用精确的上传描述信息准备 mediaImport，然后以 application/octet-stream 发送相同字节。请提供 X-Publish-Confirmation、Idempotency-Key，以及包含经 URI 编码的 JSON 描述信息的 X-Publish-Upload。字节必须与描述中的大小和 SHA-256 一致。此传输方式上限为 3 MiB；更大的受支持文件请使用上传辅助工具。上传永远不代表批准发布。

浏览 API 参考，或下载 OpenAPI 规范。