Publishing

Publish a post

Publish a video, images or text alone to one or more networks, now or at a scheduled time.

POSThttps://api.sangtao.ai/v2/publishing/posts

Authorization

X-Api-Keystring · headerrequired
Your API key, from the API keys page of your account.

202 means accepted, not published yet. Uploading and posting run in the background — from tens of seconds to a few minutes, depending on the network and the video. Follow it with Get a post.

Body

teamIdstring (guid)required
The group to publish from — its connected accounts are used
platformsobject[]required
One item per network to publish to, at least one
Show child attributesHide child attributes
- platformstringrequired
  The network, case-insensitive. X is accepted for Twitter. It must be connected in the group
  Available options:TikTokYouTubeInstagramFacebookThreadsTwitter
- captionstring
  Post text — TikTok, Facebook, Instagram, Threads, X. Required on every platform of a text-only post
- titlestring
  Video title — YouTube
- descriptionstring
  Video description — YouTube
- typestring
  Post type, to override the default (Default post type below)
  Available options:POSTREELSTORYSHORTVIDEOIMAGE
- privacystring
  TikTok: PUBLIC_TO_EVERYONE, SELF_ONLY, MUTUAL_FOLLOW_FRIENDS, FOLLOWER_OF_CREATOR. YouTube: PUBLIC, PRIVATE, UNLISTED. Left out: public
  Available options:PUBLIC_TO_EVERYONESELF_ONLYMUTUAL_FOLLOW_FRIENDSFOLLOWER_OF_CREATORPUBLICPRIVATEUNLISTED
- textFormatPresetIdstring
  Facebook text-only posts (no jobId, videoUrl or imageUrls): a coloured background behind the text. Left out: a plain text post. With an image or a video Facebook drops the background; other networks ignore it. IDs from GET /publishing/facebook/text-presets (page Facebook text backgrounds). An unknown ID is accepted here and fails when posting
- musicSoundIdstring
  TikTok image posts: the songClipId of a track from GET /publishing/tiktok/music (page TikTok music). Left out: TikTok picks one. Ignored for video posts and other networks
jobIdstring
A finished video job of yours on sangtao.ai: its video (and cover, if thumbnailUrl is left out) is posted. Takes priority over videoUrl
videoUrlstring
Public URL of the video — it must download without login and not expire before it is posted
imageUrlsstring[]
Public image URLs, up to 35; each network takes only as many as it allows (TikTok 35, Instagram 20, Threads 20, Facebook 10, X 4)
thumbnailUrlstring
Cover image for YouTube, Facebook and Instagram. TikTok takes a frame of the video instead — see coverTimeMs
coverTimeMsnumber
TikTok video: the moment of the video used as its cover, in milliseconds, 0–600000. Left out: the start
scheduleAtstring
When to publish (ISO 8601, UTC). Left out: right away
firstCommentstring
A comment posted automatically once the post is up. Facebook only for now
idempotencyKeystring
Sent again with the same key and body within 24 hours: the same post back (idempotentReplay: true), not published or charged twice. Another body with the same key: 422 IDEMPOTENCY_KEY_REUSED. Or send it as the Idempotency-Key header
webhookUrlstring
A public https URL (port 443) to POST this post’s result to when it is done — see Webhook. A bad URL is 422 INVALID_WEBHOOK_URL, before the post is made or charged
webhookSecretstring
Signs those deliveries (X-Sangtao-Signature). Up to 200 characters. Without it they come unsigned

Send one of jobId, videoUrl or imageUrls — or none of them for a text-only post (Facebook, X and Threads only, below).

IDs for textFormatPresetId: Facebook text backgrounds. Tracks for musicSoundId: TikTok music.

Text-only posts

Leave out jobId, videoUrl and imageUrls to post text alone. Then every platform must be Facebook, X (Twitter) or Threads — TikTok, YouTube and Instagram need a video or images (400 VALIDATION_ERROR names them). Each platform needs a caption; type is POST or left out. On Facebook, textFormatPresetId adds a coloured background; without it the post is plain text. Priced as any other post.

json

{
  "teamId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "platforms": [
    { "platform": "Facebook", "type": "POST", "caption": "Nội dung bài", "textFormatPresetId": "249307305544279" },
    { "platform": "X", "caption": "Nội dung bài" }
  ]
}

Default post type

Network	Video	Images only	Text only
TikTok	VIDEO	IMAGE	—
YouTube	VIDEO	—	—
Instagram	REEL	POST	—
Facebook	REEL	POST	POST
Threads	POST	POST	POST
Twitter (X)	POST	POST	POST

Each network sets its own limits — video length, aspect ratio, caption length. They are not checked before posting; a post that breaks one fails on that network, with the reason in platforms[].error.

Response

postIdstring (guid)required
The post's ID — follow it with Get a post
statusstringrequired
Pending: accepted and queued
statusMessagestring | null
A short note on the status
idempotentReplayboolean
Only there (true) when this answers a repeated idempotencyKey: the post was made earlier

What a post costs

One call to this endpoint is one post, however many networks it goes to. Scheduled posts are paid for when you make the call.

Billed in	How
Credits	A fixed number of credits per post is locked when the call is accepted (402 INSUFFICIENT_CREDITS if your balance is short). It is charged once the post has been sent off for publishing — even if a network later rejects it — and released if it fails before that, or if you delete it while still Pending.
Monthly plan	Each post uses one from the plan's monthly allowance (plus any posts bought on top). Failed and cancelled posts are not counted. When none are left: 400 QUOTA_EXCEEDED.

Errors

Status	errorCode	When
400	VALIDATION_ERROR	The body is empty, platforms is missing or empty, a platform name is unknown, coverTimeMs is out of range — or, with no jobId / videoUrl / imageUrls: TikTok, YouTube or Instagram is in platforms (they need media; error names them), a platform has no caption, or type is not POST
400	JOB_NOT_READY	The job's video has not finished rendering
400	NO_CONNECTED_ACCOUNT	A network in platforms is not connected in the group — connect it on sangtao.ai first
400	QUOTA_EXCEEDED	Monthly publishing plan: no posts left this period
402	INSUFFICIENT_CREDITS	Not enough credits for the post
403	NO_API_ACCESS	Monthly publishing plan without API access
404	TEAM_NOT_FOUND	No group of yours with this teamId
404	JOB_NOT_FOUND	No job of yours with this jobId
409	ACCOUNT_NEEDS_ATTENTION	The posting page of a network changed or was lost — pick the page again on sangtao.ai; nothing was posted or charged. details[0].params: platform, reason
422	INVALID_WEBHOOK_URL	webhookUrl is not a public https URL on port 443 — nothing was posted or charged
422	IDEMPOTENCY_KEY_REUSED	This idempotencyKey was already used for another body — use a new key
500	NO_SUBSCRIPTION	A setup problem on our side, not yours — contact support
502	PUBLISH_FAILED	Sending the post to the networks failed — try again

POST/publishing/posts

curl -X POST "https://api.sangtao.ai/v2/publishing/posts" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "teamId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "videoUrl": "https://cdn.example.com/video.mp4",
    "thumbnailUrl": "https://cdn.example.com/cover.jpg",
    "platforms": [
      {
        "platform": "TikTok",
        "caption": "Iced coffee in 3 steps #coffee",
        "privacy": "PUBLIC_TO_EVERYONE"
      },
      {
        "platform": "YouTube",
        "title": "How to make iced coffee at home",
        "description": "A three-step recipe.",
        "type": "SHORT"
      }
    ],
    "scheduleAt": "2026-11-09T02:00:00Z",
    "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000"
  }'

{
  "success": true,
  "data": {
    "postId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "status": "Pending",
    "statusMessage": "Đang chờ xử lý..."
  }
}

POST/publishing/posts

curl -X POST "https://api.sangtao.ai/v2/publishing/posts" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "teamId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "videoUrl": "https://cdn.example.com/video.mp4",
    "thumbnailUrl": "https://cdn.example.com/cover.jpg",
    "platforms": [
      {
        "platform": "TikTok",
        "caption": "Iced coffee in 3 steps #coffee",
        "privacy": "PUBLIC_TO_EVERYONE"
      },
      {
        "platform": "YouTube",
        "title": "How to make iced coffee at home",
        "description": "A three-step recipe.",
        "type": "SHORT"
      }
    ],
    "scheduleAt": "2026-11-09T02:00:00Z",
    "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000"
  }'

{
  "success": true,
  "data": {
    "postId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "status": "Pending",
    "statusMessage": "Đang chờ xử lý..."
  }
}

PreviousTikTok music NextList posts