SosoAPI 发布 API：身份验证、请求和结果

1. 从服务器进行验证

在「SosoAPI App → 设置 → agent 与 API 访问权限」创建 API key。于服务器环境存储为 SOSOAPI_API_KEY。请求使用 Authorization: Bearer <your-key> 及 Content-Type: application/json。切勿将 key 嵌入网站、移动应用套件、URL 或公开仓库。

以下所有端点皆使用 POST 与 JSON 主体。Keys 与委派 agent 授权受其能力、允许的 工作区 及所有者当前成员资格限制。读取需要 agent:operate 及至少 viewer 权限；发布变更需要 agent:publish 及至少 editor 权限。授权无法扩大所有者的权利。

使用应用的当前工作区和已连接账号，或调用 /identity-api/workspace/list 和 /identity-api/user/social-accounts/list 查找你获准使用的 ID。不要猜测客户的工作区或账号 ID。

// Node.js 20+; run only on your server.
const apiKey = process.env.SOSOAPI_API_KEY;
if (!apiKey) throw new Error("Set SOSOAPI_API_KEY on your server");
const apiBase = "https://gqeshlawtcexsapabaui.supabase.co/functions/v1";

async function sosoPost(path, body) {
  const response = await fetch(apiBase + path, {
    method: "POST",
    headers: {
      Authorization: "Bearer " + apiKey,
      "Content-Type": "application/json"
    },
    body: JSON.stringify(body)
  });
  const result = await response.json();
  if (!response.ok) {
    const requestId = result.request_id ?? response.headers.get("x-request-id");
    // Handler errors use code/message; schema-validation 400s instead use
    // success:false and error:{name:"ZodError",message:...}.
    // Preserve status, available code and requestId in server diagnostics.
    // Never log the key or an Authorization header.
    throw new Error("SosoAPI " + response.status + " (" +
      (requestId ?? "no request id") + ")");
  }
  return result;
}

2. 发布端点映射

这些路径相对于服务器辅助函数使用的 API 基础 URL。请获取排程帖子详情，以获取当前版本、可用操作与发布结果。

3. 在保留范围的前提下列出和分页

limit 默认为 50，接受 1–200。可选 status 为 scheduled、publishing、published、failed、expired、needs_reschedule、cancelled 或 deleted 之一。scheduled_from 和 scheduled_to 必须一同提供，格式为带偏移量的 ISO-8601 时刻；结束时间必须晚于开始时间。

next_cursor 为 null 或含 scheduled_at 和 id 的对象。将整个对象作为 cursor 连同相同工作区和筛选条件传回。此端点不接受 page、offset、platform 或 social_account_id 筛选。

await sosoPost("/studio-api/scheduled-posts/list", {
  "workspace_id": "<workspace-uuid>",
  "limit": 50
});

const first = await sosoPost("/studio-api/scheduled-posts/list", {
  workspace_id: "<workspace-uuid>", limit: 50
});
if (first.next_cursor) {
  const next = await sosoPost("/studio-api/scheduled-posts/list", {
    workspace_id: "<workspace-uuid>", limit: 50, cursor: first.next_cursor
  });
  // Consume next.posts; continue only while next_cursor is not null.
}

4. 验证并创建一篇已审核帖子

将所有占位符替换为授权范围内的值和未来时间。执行此示例会排程一篇真实的 Threads 文字帖子。调用创建操作前，请获得当事人对账号、内容和时间的确认。

设置 provider_payload.platform 及该平台的 publish_options。服务器会确认两者与所选账号相符。可加入 project_id 记录帖子来源；项目不会授予发布访问权限，也不会控制排程。

await sosoPost("/studio-api/scheduled-posts/eligibility", {
  "workspace_id": "<workspace-uuid>",
  "include_quota": true,
  "targets": [
    {
      "social_account_id": "<threads-account-uuid>",
      "media": [],
      "provider_payload": {
        "platform": "threads",
        "publish_options": {
          "post_type": "TEXT"
        }
      },
      "draft": {
        "caption": "A reviewed update from our team.",
        "hashtags": [],
        "scheduled_at": "<future-ISO-8601-instant-with-offset>",
        "display_timezone": "Asia/Hong_Kong"
      }
    }
  ]
});

await sosoPost("/studio-api/scheduled-posts/create", {
  "workspace_id": "<workspace-uuid>",
  "social_account_id": "<threads-account-uuid>",
  "caption": "A reviewed update from our team.",
  "hashtags": [],
  "media": [],
  "provider_payload": {
    "platform": "threads",
    "publish_options": {
      "post_type": "TEXT"
    }
  },
  "scheduled_at": "<future-ISO-8601-instant-with-offset>",
  "display_timezone": "Asia/Hong_Kong",
  "idempotency_key": "<stable-key-for-this-one-intent>"
});

5. 查看结果并安全取消

创建会返回 { post, deduped }。清单会返回 { posts, next_cursor, returned_count }。读取会返回 { post, delivery, actions, attempts, outcomes }。帖子包含 id、status、version、destination、schedule，以及可用的平台身分／永久链接；delivery 与 actions 说明当前进度与允许的下一步。

status 为 scheduled 或 publishing 的帖子仍待处理。status 为 published 的最终发布结果才确认已发布，并包含该帖子可获取的平台证据；可能缺少永久链接。如果客户端中断连接或响应延迟，请先读取现有帖子再报告结果。

取消前，先获取帖子详情并传入当前的数值 version。SosoAPI 取消平台持有的排程时，结果可能为 cancellation_pending。取消排程不会删除已发布帖子。

await sosoPost("/studio-api/scheduled-posts/get", {
  "id": "<scheduled-post-uuid>"
});

const detail = await sosoPost("/studio-api/scheduled-posts/get", {
  id: "<scheduled-post-uuid>"
});
// Run only after the person confirms cancelling this unpublished post.
await sosoPost("/studio-api/scheduled-posts/cancel", {
  id: detail.post.id, expected_version: detail.post.version
});

6. 幂等性、冲突与写入结果不明

重复同一创建请求时，使用相同的 idempotency_key。匹配的重放会返回现有帖子，且 deduped=true。复用该 key 但更改内容会导致冲突。这可防止在 SosoAPI 中重复创建，但不保证平台恰好交付一次。

更新与操作请传入最新详细响应中的 expected_version。如有冲突，请重新获取帖子，并依新版本审核变更。响应遗失时应检查现有状态，不应使用新键另建帖子。

重复内容防护可能会拒绝独立请求，如果其标准化公开内容、账号和临近发布时间相同。如获准读取，请检查现有帖子引用，并在更改请求前询问用户。批量请求会为每个目标返回结果；部分可能成功，其他则失败。

7. 错误、速率限制与集成限制

处理程序错误使用包含 error、message、可选 code、retryable、request_id、可选 details 和 retry_after_seconds 的封装。schema 验证 400 错误返回不同结构：{ success: false, error: { name: "ZodError", message: "…" } }。验证消息当前包含序列化字段问题及其路径；不要假定处理程序封装字段存在。

诊断失败时，请保留 HTTP 状态、错误码，以及 result.request_id ?? response.headers.get("x-request-id") 的关联 ID。使用验证字段路径修正请求。若为验证或权限错误，请先修正凭证或授权再重试。

studio-api 当前限制为每位人工用户每分钟 240 个请求，以及该用户独立机器凭证配额桶每分钟 480 个请求。这是请求上限，不是发布吞吐量或套餐配额。其他端点和社交平台有各自限制。收到 429 或可重试 503 时，遵循实时 Retry-After 响应头；不要忙循环。

用户跟进帖子期间，以有界间隔读取状态，或使用应用实时状态视图。此 API 不承诺向外发送 webhooks、订阅者 SLA、各平台功能一致或固定发布时间。

• 平台能力对照表
• 设置你自己的 AI agent