--- sidebar: order: 1 title: HTTP API description: 通过现有 HTTP API 完成身份验证、发现工具并确认变更。 --- 向可信的 Influence 源站（例如 `https://influence.so`）发送产品 API 请求。文档域名不接收产品 API 请求。请使用下列精确路径，不添加查询参数。 ## 创建限定权限的 API 密钥 [#create-a-scoped-api-key] 在 [Influence 设置](https://influence.so/sign-in?next=%2Fapp%2Fsettings%2Faccount%23settings-developer)中，打开应用与自动化 → API 密钥。选择所需权限和有效期。密钥只展示1次，请将其存入机密存储，命名为 `PUBLISH_API_TOKEN`。通过 `Authorization: Bearer …` 发送密钥，切勿放入 URL、请求正文或聊天。无需使用时，请撤销密钥。 ## 发现工具并读取账号 [#discover-tools-and-make-a-read] 将 `PUBLISH_API_URL` 设为可信源站。以下示例假定进程已持有 `PUBLISH_API_TOKEN`。`accountList` 需要 `integrations:read` 权限；请按其分页字段继续获取后续页面。 ```sh 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":{}}' ``` ## 请求路径 [#request-paths] | 方法 | 路径 | 用途 | | --- | --- | --- | | `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":{…}}`。各工具的输入结构请从当前工具目录获取。 ## 准备并确认操作 [#prepare-and-confirm-actions] 以目录中的 `confirmation` 字段为准：读取通常无需确认，但数据洞察刷新虽然属于读取，仍需确认。上传分片查询、完成和取消操作通过 `/call` 继续已获授权的上传。 1. 将精确的业务输入发送至 `/prepare`。成功响应包含 `status: "confirmation_required"`、`confirmationCapability`、`expiresAt`、`inputDigest`，以及可选的 `summary`。 2. 在过期前，将相同输入发送至 `/confirm`。在 `X-Publish-Confirmation` 中提供返回的确认凭据，并在 `Idempotency-Key` 中提供调用方新生成的幂等键。 3. 将输入、确认凭据和幂等键保存在一起。如果确认过程被中断，或结果不确定，请为同一请求复用这3项值。不要为恢复不确定的结果重新准备替代请求。 幂等键包含16–200个字符，可用字符为 `A–Z`、`a–z`、`0–9`、`.`、`_`、`:` 和 `-`。确认凭据是不透明的机密值。向 `/call` 或 `/prepare` 发送幂等键，不会预留已确认的写入。 传输确认与发布批准是不同步骤。发布或更改定时安排前，请展示完整的当前审核内容：账号、文案、设置、实际素材预览或链接、定时发布时间及时区。对于符合条件的社交文字、图片和视频审核，客户端可通过 `approval: "approved"` 报告新的明确人工批准；不得编造同意，也不得把准备操作视为批准。Influence 将此记录为客户端报告的批准。受支持的嵌入式卡片或登录后的审核会记录各自的人工操作。 TikTok Direct 支持通过[审核流程](/zh-Hans/developers/mcp#prepare-finished-content)取得明确的聊天选择与同意。使用 `campaignReview` 保存完整选择，然后先取得对更新后审核内容的重新批准，再执行。审核卡片可选。普通 API/CLI 定时发布不消耗 AI 定时发布额度；单独的 [MCP 与 Influence IQ 额度](/zh-Hans/help/ai-assistants#scheduling-allowance)适用于这些流程，即使保存的 AI 审核稍后在 Influence 中获批，也按该额度计算。其他套餐与平台要求仍然适用。继续操作前，请读取已保存的回执；`needs_review` 要求核对并处理当前状态，不能再次发送。 ## 处理错误与不确定的结果 [#handle-errors-and-uncertain-results] 同时检查 HTTP 状态和响应正文。工具成功时返回 `{"ok":true,"toolName":"…","output":{…}}`。工具失败时返回 `{"ok":false,"toolName":"…","error":{"code":"…","message":"…","retryable":false}}`，HTTP 状态仍可能为 200。传输失败使用 `{"error":{"code":"…","message":"…","retryable":false}}`，不含 `ok` 或 `toolName`。 401 表示需要身份验证，请检查凭据是否过期或已撤销。缺少权限时，需要取得相应授权，重复请求无济于事。503 可能表示服务不可用，或另一个定时发布请求正在更新工作区。请遵循返回的错误码与重试指引，不要自动重放发布操作。超时并不证明写入失败：请保留确认数据，并在重新提交前读取当前状态。已受理、已定时发布和已发布是不同结果。 ## 上传素材 [#upload-media] 上传本地文件时，优先使用 SDK 的 `uploadMedia` 或 CLI 的 `media:upload`。它们使用相同的分片上传工具，并保留稳定的 `clientKey` 供重试。只有带 `assetId` 的就绪结果才能附加到内容中。对于已获授权的 HTTPS 链接，请使用 `mediaImport`，传入 `url` 和可选的 `name`。真实的宿主文件引用使用独立的 `file` 对象；公共 URL 不需要虚构的宿主文件 ID。本地文件路径不是下载 URL。请参阅[素材限制](/zh-Hans/help/media)：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 参考](/zh-Hans/api-reference)，或[下载 OpenAPI 规范](/specs/influence.openapi.json)。