出刊室 / 发布 API 使用说明

十个平台的本地视频和图文命令见文末「按平台复制命令」。

服务地址 https://tiktok-publish-oauth.xpfasd7719.workers.dev
网页工作台 /studio    OAuth 连接 /connect    OAuth 回调清单 /platforms
所有 /v1 请求使用 Authorization: Bearer <PUBLISH_API_TOKEN>。管理员密钥也可使用。
Mac 钥匙串中两个项目分别叫 Social Publisher ADMIN_TOKEN 与 Social Publisher PUBLISH_API_TOKEN。
发布密钥可向已经连接的账号投递内容、读取账号列表和作品数据。请仅在自己的后端、CLI 或可信应用中使用。
API 文档公开可读。工作台解锁后，同一浏览器会记住登录状态，手动锁定后需要重新解锁。页面不展示服务端保存的媒体平台令牌。

快速开始（macOS 终端；先完成真实账号授权）
  BASE=https://tiktok-publish-oauth.xpfasd7719.workers.dev
  TOKEN="$(security find-generic-password -a social-publisher -s 'Social Publisher PUBLISH_API_TOKEN' -w)"
  curl -fsS "$BASE/v1/accounts" -H "Authorization: Bearer $TOKEN"

一次请求上传并排队
  将下列 JSON 保存为 manifest.json，将 CONNECTION_UUID 换为 /v1/accounts 返回的账号 ID。
  {
    "title":"本周制作记录",
    "text":"这周的制作过程和成片。",
    "consent":true,
    "targets":[{"connection_id":"CONNECTION_UUID","options":{"privacy":"unlisted","kids":false}}]
  }
  这个示例对应 YouTube 视频。普通 X、Instagram、Threads 等目标只需 connection_id。
  每个作品生成一次 KEY 并保留。网络超时后使用原 KEY、相同清单和相同文件重试。
  KEY="$(uuidgen)"
  curl -fsS "$BASE/v1/works" -H "Authorization: Bearer $TOKEN" -H "Idempotency-Key: $KEY" \
    -F 'manifest=<manifest.json' -F 'file=@./clip.mp4;type=video/mp4'
  HTTP 202 返回 work_id。原样重试返回同一个 work_id；同一 KEY 不同内容返回 409。

两步提交或复用素材
  curl -fsS "$BASE/v1/media" -H "Authorization: Bearer $TOKEN" \
    -H 'Content-Type: image/jpeg' --data-binary @./cover.jpg
  返回 asset_id。用下面的 JSON 调 POST /v1/works（Content-Type: application/json，并传 Idempotency-Key）。
  {"asset_id":"上一步的素材ID","title":"新作品","text":"正文","consent":true,"targets":[{"connection_id":"账号ID"}]}
  纯文字省略 asset_id。支持 JPEG、PNG、MP4，一件作品一份素材，单文件不超过 32 MiB。上传时发送 Content-Length。
  提交中可添加 ISO 8601 的 publish_at，如 2026-11-05T10:30:00+08:00。省略即下次扫描发布，最长提前 7 天。
  素材位于独立 R2，持有完整素材链接者可以读取，便于媒体平台拉取。R2 设置了 30 天过期规则。密钥不出现在素材链接中。

查询与管理
  GET  /v1/status                           最近一次真实定时扫描时间和领取数量
  GET  /v1/accounts                         账号 ID、备注、平台和格式能力
  GET  /v1/accounts/{id}/destinations       Facebook 主页、Pinterest 画板或 TikTok 创作者选项
  POST /v1/media                            原始文件字节上传
  POST /v1/works                            创建作品，可传 multipart 或 JSON
  GET  /v1/works/{work_id}                  所有目标账号的独立状态
  GET  /v1/works                            任务列表，每页 150 条，支持 account=账号ID 和 before=next_cursor
  POST /v1/works/{work_id}/cancel           取消仍在 queued 的账号任务
  POST /v1/jobs/{job_id}/metrics            向官方平台查询此作品并保存快照
  GET  /v1/jobs/{job_id}/metrics            最近 90 条快照和采集时间
  GET  /api/events                          已验签的通知记录（仅管理员）
  PUT  /v1/tiktok-verification/{filename}   写入 TikTok 官方域名验证文件原文（仅管理员；文件名 tiktok…txt）

定时运行
  Cloudflare Cron 每分钟领取最多 3 个到期账号任务。多账号使用同一作品编号，逐账号记录结果。
  queued 等待、running 执行、processing 平台处理、awaiting_creator 等待创作者、published 已发布、
  failed 明确失败、review 需要核对、cancelled 已取消。HTTP 202 表示已进入队列。
  无法确认平台是否已创建作品时进入 review，需先在平台核实。出现明确的限流或临时读取故障会退避重试。
  指标查询由网页按钮或外部程序调用，可能消耗官方 API 配额或费用。缺少权限、没有作品 ID、无数据和零次互动分别处理。

账号目标与官方数据能力（当前实现）
  TikTok：MP4、图片。默认 Content Posting /收件箱上传；用户在 TikTok 编辑确认后发布。
    必须验证 MEDIA_BASE_URL 对应域名或 URL 前缀以使用 PULL_FROM_URL，并配置 video.upload。
    TikTok Direct Post 审核指南把仅供自己或团队管理账号的上传工具明确列为不接受的用例。
    只有用途及客户端已获准时才设置 TIKTOK_DIRECT_ENABLED=true 和适用 TIKTOK_SCOPES。
    直接模式 options 需 mode=direct、privacy、creator_consent=true、music_consent=true；商业披露按实际选 own_brand/paid_brand。
    直接发布视频需提供 duration（秒）。可见性由 creator_info 返回。当前直发互动开关全部关闭。
    查询公开作品观看、点赞、评论、分享使用 video.list 和公开作品 ID；私密或仅送达的作品无此项数据。
    https://developers.tiktok.com/docs/en/content-sharing-guidelines
    https://developers.tiktok.com/docs/en/content-posting-api-reference-get-video-status
    https://developers.tiktok.com/doc/tiktok-api-v2-video-query/
  Facebook Pages：文字、单图、视频。选择 options.destination=真实 Page ID；使用所选主页的 Page token。
    可请求互动计数，视频可请求 views；实际字段依 API 版本、对象和 Page 权限。
    https://developers.facebook.com/docs/pages-api/posts/
    https://developers.facebook.com/docs/graph-api/reference/video/
  Instagram：专业账号，JPEG 单图、Reels 视频。创建容器，查询 status_code，再发 media_publish。
    可请求 views、reach、likes、comments、shares，需 Instagram Insights 权限及适用媒体类型。
    https://developers.facebook.com/docs/instagram-platform/content-publishing/
    https://developers.facebook.com/docs/instagram-platform/insights/
  YouTube：MP4 视频，使用 resumable upload，查询处理状态。需 title、options.privacy 及布尔 options.kids。
    privacy 取 private/unlisted/public。未审核项目可能被限制为私密。查询播放、喜欢、评论等 videos.statistics。
    https://developers.google.com/youtube/v3/docs/videos/insert
    https://developers.google.com/youtube/v3/docs/videos/list
  Threads：文字、单图、视频。容器完成后发布，可请求 views、likes、replies、reposts、quotes。
    读取需 threads_manage_insights。https://github.com/fbsamples/threads_api
  X：文字、单图、视频。媒体分片上传，处理后创建帖子。查询 tweet.fields=public_metrics。
    需支持这些端点的开发者产品、写入范围及足够配额，费用由 X 账号设置决定。
    https://docs.x.com/x-api/posts/create-post
    https://docs.x.com/x-api/fundamentals/metrics
  LinkedIn：个人文字、单图。需 openid/profile/w_member_social；通过 userinfo 取得成员 ID。
    读取 socialActions 的点赞/评论摘要需要单独批准的读取权限。接口可用性取决于获批产品。
    https://learn.microsoft.com/en-us/linkedin/marketing/community-management/shares/posts-api
    https://learn.microsoft.com/en-us/linkedin/marketing/community-management/shares/network-update-social-actions
  Pinterest：图片 Pin。options.destination 为画板 ID，可查近 7 个完整 UTC 日的曝光、保存及点击汇总。
    https://developers.pinterest.com/docs/api/v5/pins-create/
    https://developers.pinterest.com/docs/api/v5/pins-analytics/
  Mastodon：当前连接 mastodon.social，文字、单图、视频。查询喜欢、回复、转发。
    建立 OAuth 应用后配置 MASTODON_CLIENT_ID / MASTODON_CLIENT_SECRET，登记 /oauth/mastodon/callback。
    https://docs.joinmastodon.org/methods/media/
    https://docs.joinmastodon.org/methods/statuses/
  Bluesky：bsky.social 托管账号，网页“账号”中使用应用专用密码连接。仅保存会话令牌。
    支持文字和不超过 1 MB 的单图，查询喜欢、回复、转帖、引用。未接入自托管 PDS。
    https://docs.bsky.app/docs/advanced-guides/posts
    https://docs.bsky.app/docs/api/app-bsky-feed-get-posts

部署凭据
  ADMIN_TOKEN 管理账号授权及完整管理接口。PUBLISH_API_TOKEN 只用于发布与数据工作台。
  各平台 OAuth Client ID / Secret、重定向地址、产品审批与读写 scopes 按项目 README 和 /platforms 配置。
  已经连接的旧账号如果缺少新增的读写权限，需要重新授权。
  作品清单、账号级任务和指标快照保存在 D1。作品账号真实连通性以平台返回的授权结果、作品 ID 和指标为准。


本地直发（媒体不经过 Cloudflare）
  先在工作台授权要使用的账号。下列命令在自己的终端或后端运行，需要 curl 和 jq。
  BASE=https://tiktok-publish-oauth.xpfasd7719.workers.dev
  KEY="$(security find-generic-password -a social-publisher -s 'Social Publisher ADMIN_TOKEN' -w)"
  curl -fsS "$BASE/v1/accounts" -H "Authorization: Bearer $KEY" | jq '.accounts[] | {id,provider,label}'
  ACCOUNT='替换为目标账号的 id'
  ACCESS="$(curl -fsS -X POST "$BASE/v1/accounts/$ACCOUNT/publish-token" -H "Authorization: Bearer $KEY" | jq -er '.access_token')"

  POST /v1/accounts/{id}/publish-token 要求显式传入管理员 Bearer 密钥。响应仅含 access_token、token_type、
  connection_id、platform、subject 和 expires_at（Unix 毫秒，null 表示未知）。令牌沿用该账号已授予的权限。
  官方访问令牌只能交给可信调用者。临近过期时重新领取；平台要求重新授权时，在工作台重新连接。
  Facebook Pages 先 GET /v1/accounts/{id}/destinations 选主页，再在领取地址末尾加 ?page_id=主页ID，
  得到该主页的令牌。Pinterest 按发布目标选择 board_id。Bluesky 返回账号的 access JWT。
  本地调用方负责保存平台作品 ID、查询发布状态和处理重试。本地直发不会自动出现在工作台任务列表。

  示例：本地视频发到 YouTube（先按上面步骤选择 YouTube 账号）。以下命令会创建一条私享视频。
  FILE='./clip.mp4'
  UPLOAD="$(curl -fsS -D - -o /dev/null -X POST 'https://www.googleapis.com/upload/youtube/v3/videos?uploadType=resumable&part=snippet,status' \
    -H "Authorization: Bearer $ACCESS" -H 'Content-Type: application/json' -H 'X-Upload-Content-Type: video/mp4' \
    --data '{"snippet":{"title":"本地视频","categoryId":"22"},"status":{"privacyStatus":"private"}}' | awk 'tolower($1)=="location:" {sub(/\r$/,"",$2); print $2}')"
  curl -fsS -X PUT "$UPLOAD" -H 'Content-Type: video/mp4' --data-binary "@$FILE"
  官方指南 https://developers.google.com/youtube/v3/guides/using_resumable_upload_protocol

  TikTok 使用 FILE_UPLOAD 初始化并将本地视频 PUT 到官方返回的 upload_url；video.upload 会投递收件箱，
  创作者需在 TikTok 确认，直接发布需要 video.publish 及平台相应批准。
  https://developers.tiktok.com/doc/content-posting-api-media-transfer-guide
  X、Mastodon、LinkedIn 等按平台媒体上传流程获取媒体 ID 后创建作品。使用要求公开媒体 URL 的接口时，
  可提供调用者自己的 HTTPS 素材地址，本机文件路径无法供平台抓取。

按平台复制命令（Python 3.9+，macOS / Linux）
  先准备一个工作目录，下载可阅读的示例客户端并安装依赖。以下命令都在同一终端运行。
  python3 -m venv .publish-env
  . .publish-env/bin/activate
  python -m pip install requests
  BASE=https://tiktok-publish-oauth.xpfasd7719.workers.dev
  curl -fsS "$BASE/local-publish.py" -o local-publish.py
  python local-publish.py --help

  第一次先找到账号。以下命令会提示输入工作台密钥（终端不回显）。
  export PUBLISHER_KEY="$(python -c 'import getpass; print(getpass.getpass("工作台密钥: "))')"
  curl -fsS -H "Authorization: Bearer $PUBLISHER_KEY" "$BASE/v1/accounts" | python -m json.tool
  export ACCOUNT='替换为这次要发的平台账号 id'

  切换账号时重新设置 ACCOUNT。脚本会核对所选平台，向工作台领取令牌，然后直接请求官方 API。
  命令会实际提交作品。请先改文案、文件和目标账号；本地示例使用 MP4、JPEG，每次提交一个视频或一张配文图片。
  示例里的 HTTPS 地址请换成平台能直接下载的真实素材。处理超时或网络中断时先核对平台后台，再决定是否重试。
  Facebook / Pinterest 查主页或画板 ID：
  curl -fsS -H "Authorization: Bearer $PUBLISHER_KEY" "$BASE/v1/accounts/$ACCOUNT/destinations" | python -m json.tool

TikTok
  当前授权使用 video.upload：视频和图文均送至创作者收件箱，在 TikTok 内确认发布。视频配文在应用内编辑。图片 URL 必须位于开发者已验证的域名或 URL 前缀下。
  # 视频
  python local-publish.py tiktok video "./clip.mp4" --title "作品标题" --text "我的作品文案"
  # 图文
  python local-publish.py tiktok image "https://media.example.com/cover.jpg" --title "作品标题" --text "我的作品文案"
  官方参考 https://developers.tiktok.com/doc/content-posting-api-reference-photo-post

YouTube
  示例上传私享视频；图文：YouTube Data API 没有创建社区图片帖的公开方法，请在 YouTube 界面创建。
  # 视频
  python local-publish.py youtube video "./clip.mp4" --title "作品标题" --text "我的作品文案"
  官方参考 https://developers.google.com/youtube/v3/docs

Facebook Pages
  先设置 PAGE_ID 为 destinations 返回的目标主页 ID，两种格式都从本地上传到该主页。
  PAGE_ID='替换为主页 ID'
  # 视频
  python local-publish.py facebook video "./clip.mp4" --title "作品标题" --text "我的作品文案" --page "$PAGE_ID"
  # 图文
  python local-publish.py facebook image "./cover.jpg" --title "作品标题" --text "我的作品文案" --page "$PAGE_ID"
  官方参考 https://developers.facebook.com/docs/pages-api/posts/

Instagram
  专业账号。Reels 视频和图片都使用公网 URL；脚本会等待容器处理完成再发布。
  # 视频
  python local-publish.py instagram video "https://media.example.com/clip.mp4" --title "作品标题" --text "我的作品文案"
  # 图文
  python local-publish.py instagram image "https://media.example.com/cover.jpg" --title "作品标题" --text "我的作品文案"
  官方参考 https://developers.facebook.com/docs/instagram-platform/content-publishing/

Threads
  视频和图片都使用公网 URL；脚本会等待容器就绪再发布。
  # 视频
  python local-publish.py threads video "https://media.example.com/clip.mp4" --title "作品标题" --text "我的作品文案"
  # 图文
  python local-publish.py threads image "https://media.example.com/cover.jpg" --title "作品标题" --text "我的作品文案"
  官方参考 https://developers.facebook.com/docs/threads/posts/

X
  从本地分段上传素材，再创建带文案的帖子。账号授权和应用套餐需允许媒体上传及发帖。
  # 视频
  python local-publish.py x video "./clip.mp4" --title "作品标题" --text "我的作品文案"
  # 图文
  python local-publish.py x image "./cover.jpg" --title "作品标题" --text "我的作品文案"
  官方参考 https://docs.x.com/x-api/media/quickstart/media-upload-chunked

LinkedIn
  发到已授权会员的个人动态；视频按官方返回的字节范围上传，图片先上传再关联到帖子。需要相应产品权限。
  # 视频
  python local-publish.py linkedin video "./clip.mp4" --title "作品标题" --text "我的作品文案"
  # 图文
  python local-publish.py linkedin image "./cover.jpg" --title "作品标题" --text "我的作品文案"
  官方参考 https://learn.microsoft.com/en-us/linkedin/marketing/community-management/shares/videos-api

Pinterest
  先设置 BOARD_ID 为目标画板 ID。视频还需一张公开可读取的封面图；图片示例直接使用本地 JPEG。
  BOARD_ID='替换为画板 ID'
  # 视频
  python local-publish.py pinterest video "./clip.mp4" --title "作品标题" --text "我的作品文案" --board "$BOARD_ID" --cover "https://media.example.com/cover.jpg"
  # 图文
  python local-publish.py pinterest image "./cover.jpg" --title "作品标题" --text "我的作品文案" --board "$BOARD_ID"
  官方参考 https://developers.pinterest.com/docs/api/v5/

Mastodon
  适用于工作台接入的 mastodon.social 账号。等待附件处理后发布公开嘟文。
  # 视频
  python local-publish.py mastodon video "./clip.mp4" --title "作品标题" --text "我的作品文案"
  # 图文
  python local-publish.py mastodon image "./cover.jpg" --title "作品标题" --text "我的作品文案"
  官方参考 https://docs.joinmastodon.org/methods/media/

Bluesky
  使用工作台所连 Bluesky 托管账号。视频使用官方简单上传方式，帖子创建后视频可能仍在转码；用 --title 填素材的替代文本。
  # 视频
  python local-publish.py bluesky video "./clip.mp4" --title "作品标题" --text "我的作品文案"
  # 图文
  python local-publish.py bluesky image "./cover.jpg" --title "作品标题" --text "我的作品文案"
  官方参考 https://docs.bsky.app/docs/tutorials/video

  使用完毕后可运行 unset PUBLISHER_KEY ACCOUNT 清除当前终端变量。