开发者

公开发布 API

上传素材、创建内容，并发布到 Facebook、Instagram、TikTok、LinkedIn、Threads 和 Pinterest，全部通过工作区 API 密钥限定到某个产品范围内。推荐的集成方式是 Connect API，一个精简、扁平的 /api/connect/v1 接口，绝大多数排期工具都能直接对接。

需要更完整的控制能力，显式发布、任务执行状态轮询、已签名 Webhook、批量操作、按渠道配置？下方更高级的 /api/public/v1 API 提供了这一切功能。两者共享相同的认证方式、产品体系和发布流水线；请仅使用这些带版本号的公开路由（内部应用路由需要 Firebase 用户认证，不属于公开接口约定的一部分）。

Facebook、Instagram 和 TikTok 在 API 层面同样以人工优先。 这些渠道默认使用 manual_reminder：Markaestro 不调用平台 API，而是将内容移入「待发布」队列。传入 deliveryMode: "direct_publish" 可选择官方 API 发布。TikTok 默认转交至收件箱；当 settings.postMode 为 direct_post 时则请求 Direct Post。LinkedIn、Threads 和 Pinterest 默认以程序化方式发布。

一个工作区可以拥有多个产品。每个 API 密钥在创建时都会绑定到一个产品，因此调用会自动定向到该产品，针对其他产品的请求将被拒绝。

正在构建 AI 代理？

建议改从 AI 代理指南开始阅读。其中包含可直接复制粘贴的工具 Schema、系统提示词简介、代理所需的重试与错误处理规则，以及一份四命令快速入门。你的代理也可以直接读取 /llms.txt。

机器可读规范

以 OpenAPI 3.1 提供每个端点、请求与响应结构以及错误码。它由 API 校验所用的同一套 schema 生成，因此不会描述我们并未提供的接口。

Connect API

推荐

默认的集成方式：一个位于 /api/connect/v1、扁平且采用 snake_case 命名的接口，绝大多数排期工具都能直接对接。它将常见的 create-upload-url → PUT → post 流程，映射到与下方完整 API 相同的工作区、认证、产品体系和发布流水线上。请将客户端的基础 URL 设置为 /api/connect，并使用限定产品范围的工作区 API 密钥进行认证（权限范围：posts.read、posts.write、media.write）。

GET/api/connect/v1/social-accounts

以扁平账号列表返回已连接的 Facebook、Instagram、TikTok 和 LinkedIn 目标，每个都标注所属产品，便于客户端分组和区分。每个渠道有各自的专用路径，不做跨渠道扇出。

GET/api/connect/v1/products

列出品牌（接口命名为 products），并嵌套显示各自已连接的账号，以品牌为优先的选择器。

POST/api/connect/v1/media/create-upload-url

返回一个短时有效、一次性使用的已签名 PUT URL，以及一个素材 ID。

PUT<upload_url>

将图片的原始字节数据上传至该已签名 URL。无需 API 密钥，签名本身即完成授权。

POST/api/connect/v1/posts

为每个选定账号创建一份草稿。设置 is_draft=false 并附带 scheduled_at 即可排期投递；TikTok 使用创作者收件箱转交方式。

GET/api/connect/v1/posts

以扁平化的状态、文案和素材 URL 列出工作区内容。

# 1. List connected accounts
curl "$MARKAESTRO_URL/api/connect/v1/social-accounts" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY"

# 2. Request a signed upload url, then PUT the bytes
curl -X POST "$MARKAESTRO_URL/api/connect/v1/media/create-upload-url" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mime_type": "image/png", "size_bytes": 184320, "name": "slide-1.png" }'
curl -X PUT "<upload_url>" -H "Content-Type: image/png" --data-binary @slide-1.png

# 3. Create a draft post for one or more accounts
curl -X POST "$MARKAESTRO_URL/api/connect/v1/posts" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "New drop",
    "media": ["ast_111", "ast_222"],
    "social_accounts": ["prod_123#instagram:instagram:ig_123"]
  }'

/social-accounts 返回的每个账号都会标注其 product，表示品牌的接口命名（同一账号可能出现在多个品牌下），其 id 编码了 productId#destinationId，你可以将其原样传回 social_accounts，此时请求会按账号数量扩散为多篇内容。每个密钥仅绑定一个品牌，因此只能查看并发布到该品牌。Facebook、Instagram 和 TikTok 的内容以人工优先，均以草稿形式创建，由工作区所有者从 Markaestro 的「待发布」队列中原生发布，绝不通过平台 API 直接发布。LinkedIn、Threads 和 Pinterest 会在明确的发布操作后以程序化方式发布。内容状态为 draft、processing、posted 或 failed 之一。Facebook、Instagram、LinkedIn、TikTok 和 Threads 各自拥有独立的专属发布目标，发布到其中一个渠道不会扩散到其他渠道。可通过 GET /api/connect/v1/posts 跟踪发布状态。

高级功能：完整版公开 API

完整的 /api/public/v1 接口，显式发布、异步任务执行、已签名 Webhook、批量创建，以及按渠道配置。当 Connect API 无法满足需求时可使用此接口。

Meta 与 TikTok 以人工优先

Facebook、Instagram 和 TikTok 的内容默认进入手动「待发布」队列，不会调用平台 API，由工作区所有者原生发布并确认。可通过 deliveryMode 按内容选择改用 API 发布。

支持 Instagram 登录

即使未连接 Facebook 主页，品牌也可以开放独立的 Instagram 专业账号。

TikTok 支持两种可选路径

API 发布默认使用收件箱转交。如果 TikTok 应用已获批准，可同时设置隐私级别并将 settings.postMode 设为 direct_post 来请求 Direct Post。

设计上即为异步

每次发布都会返回一个任务 ID。请轮询任务状态或订阅已签名的 Webhook，而不是假定发布会同步完成。

品牌与发布目标

查询该 API 密钥可用的品牌与发布目标。品牌在接口层面被称为 products，为保持向后兼容，路径和请求体均使用 products/productId，POST 请求体也接受 brandId 作为别名。

GET/api/public/v1/products

列出该密钥所拥有的品牌，以及每个品牌当前可用的渠道。

GET/api/public/v1/products/:id/destinations

列出该品牌的发布目标，包括独立的 Instagram 登录、Facebook 主页、Threads、LinkedIn 个人资料/主页，以及已连接的 TikTok 发布目标。

素材

在创建内容之前，先将图片或视频上传至 Markaestro 托管的存储空间。

POST/api/public/v1/media/upload-sessions

使用文件名、内容类型和精确大小创建一个有效期为 15 分钟的直传会话。

PUT<uploadSession.uploadUrl>

使用返回的 Content-Type 将字节直接上传到存储；不要发送 API 密钥。

POST/api/public/v1/media/upload-sessions/:id/finalize

验证类型和大小并返回媒体素材；已完成的会话可安全重试。

POST/api/public/v1/media

兼容用多部分上传。返回素材 ID 和托管 URL。

内容

为 Facebook、Instagram、LinkedIn、Threads、Pinterest 和 TikTok 创建、列出、查看、发布及删除内容。

POST/api/public/v1/posts

在工作区中创建草稿。Facebook、Instagram 和 TikTok 默认使用手动发布（deliveryMode manual_reminder）；传入 deliveryMode direct_publish 可选择改用 API 发布。

GET/api/public/v1/posts

按最新优先列出内容。使用 ?status=scheduled 筛选出排期中的内容，使用 ?productId= 限定到某个品牌。品牌绑定的密钥始终只限于其自身品牌，可省略 productId。

GET/api/public/v1/posts/:id

返回当前内容状态、投递方式和发布结果。

POST/api/public/v1/posts/:id/publish

将一次异步发布任务加入队列。手动内容会进入工作区的「待发布」队列以供原生发布；LinkedIn、Threads 和 Pinterest 直接发布；已选用 API 的 Meta 内容通过官方 API 发布，已选用 API 的 TikTok 内容使用收件箱转交方式。

DELETE/api/public/v1/posts/:id

从 Markaestro 中删除该内容。使用现有的 posts.write 权限范围。如果发布任务正在进行中，将返回 400 VALIDATION_POST_IS_PUBLISHING。删除已发布的内容不会撤回平台上已发布的副本。

任务与 Webhook

通过轮询或已签名的 Webhook 投递方式跟踪异步任务。

GET/api/public/v1/job-runs/:id

返回 queued、running、succeeded 或 failed。

POST/api/public/v1/webhook-endpoints

注册一个 Webhook 目标；每个工作区最多可有 25 个活跃端点。

GET/api/public/v1/webhook-endpoints

列出该 API 密钥权限范围下已注册的 Webhook 目标。

DELETE/api/public/v1/webhook-endpoints/:id

停用某个 Webhook 目标。

1. 列出产品

查询该 API 密钥可以定向到哪些产品。

curl "$MARKAESTRO_URL/api/public/v1/products" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY"

2. 查看发布目标

在创建内容之前，查看某个产品下已关联的主页和账号。当某个产品拥有多个发布目标时（例如一个 LinkedIn 个人资料加多个主页），请使用返回的 destinationId。

curl "$MARKAESTRO_URL/api/public/v1/products/prod_123/destinations" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY"

3. 上传素材

每篇内容都会引用先前已上传的素材资源。

# 1. Create a 15-minute upload session
UPLOAD=$(curl -s -X POST "$MARKAESTRO_URL/api/public/v1/media/upload-sessions" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fileName":"launch-1.jpg","contentType":"image/jpeg","sizeBytes":184320}')

# 2. PUT bytes directly to uploadSession.uploadUrl with its returned headers
curl -X PUT "<upload_url>" -H "Content-Type: image/jpeg" --data-binary @launch-1.jpg

# 3. Finalize; the response contains asset.id for mediaAssetIds
curl -X POST "$MARKAESTRO_URL/api/public/v1/media/upload-sessions/<session_id>/finalize" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY"

4. 创建内容

使用这些素材 ID 创建草稿。Instagram 默认使用手动发布；添加 "deliveryMode": "direct_publish" 即可为该内容选用官方 API 发布。

curl -X POST "$MARKAESTRO_URL/api/public/v1/posts" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: post-001" \
  -d '{
    "channel": "instagram",
    "caption": "Launch day carousel",
    "mediaAssetIds": ["ast_123", "ast_124"],
    "productId": "prod_123",
    "destinationId": "instagram:instagram:ig_123"
  }'

TikTok 示例

TikTok 内容会以 Markaestro 草稿的形式到达，并默认从「待发布」队列中手动发布。使用 deliveryMode: "platform_inbox"（或 direct_publish），一次显式发布会将草稿改为发送至创作者的 TikTok 收件箱。

curl -X POST "$MARKAESTRO_URL/api/public/v1/posts" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: post-tt-001" \
  -d '{
    "channel": "tiktok",
    "caption": "Spring drop teaser",
    "mediaAssetIds": ["ast_vid_123"],
    "productId": "prod_123",
    "destinationId": "tiktok:tiktok:tt_open_123"
  }'

5. 排队发布

发布操作会创建一个异步任务。手动内容（Facebook/Instagram/TikTok 的默认方式）会移入「待发布」队列并触发 post.action_required；LinkedIn、Threads、Pinterest 以及已选用 API 的 Meta 内容直接发布；已选用 API 的 TikTok 内容将排队进行收件箱转交。

curl -X POST "$MARKAESTRO_URL/api/public/v1/posts/pst_123/publish" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY" \
  -H "Idempotency-Key: publish-001"

6. 查看排期并取消

列出某个品牌当前排期中的内容，删除任何你不再想要发布的内容。这两个操作均使用现有密钥已具备的权限范围，posts.read 和 posts.write。

# The key is already bound to one brand
curl "$MARKAESTRO_URL/api/public/v1/posts?status=scheduled&limit=100" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY"

# Cancel one
curl -X DELETE "$MARKAESTRO_URL/api/public/v1/posts/pst_123" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY"

Webhook 负载示例

投递内容使用你的 Webhook 密钥进行 HMAC 签名。

{
  "id": "evt_123",
  "type": "post.action_required",
  "createdAt": "2026-04-08T18:06:10.000Z",
  "workspaceId": "ws_123",
  "data": {
    "postId": "pst_123",
    "channel": "instagram",
    "status": "platform_action_required",
    "nextAction": "post_manually_from_reminder"
  }
}

渠道行为

由公开 API 强制执行的校验与投递规则。

Facebook

支持纯文字、图片或视频内容。每篇内容最多 10 张图片或 1 个视频。默认为手动发布；选用 API 后可直接发布。

Instagram

至少需要一张图片或一个视频，最多 10 项内容。单个视频将以 Reel 形式发布。默认为手动发布；选用 API 后可直接发布。

TikTok

至少一张图片或一个视频。最多 35 张图片或 1 个视频。默认人工发布；选择开启的帖子会进入创作者的 TikTok 收件箱，或通过 TikTok 的 postMode direct_post 直接发布到主页。

支持文字、单图、单视频，或最多 20 张图片的原生多图内容。可定向到已连接的个人资料，或已管理的主页。

文本、最多四张图片、一个 GIF 或一个视频。回复权限按帖子应用；当工作区的 X 成本预算耗尽时，发布会被阻止。