Skip to main content
Post a video to one of the user’s connected social accounts, then poll for the result. The REST equivalents are POST and GET /v1/videos/{id}/publish. A publish posts under the user’s own account, often publicly, so confirm the destination, text and privacy with the user before calling publish_to_social. Before publishing:
  • The account must already be connected in Tella, under Settings → Connections or Share → Publish. These tools can’t connect one; an unconnected destination returns a forbidden error.
  • Publishing uploads an existing completed export. Call export_video with the settings you want, poll get_export_status until it is completed, then pass the same export settings to publish_to_social. If no completed export matches, the call returns a conflict error.
  • TikTok isn’t available: its consent form must be completed in the Tella app.
Typical agent flow:
  1. export_video with {videoId} (and any resolution, fps, subtitles, speed)
  2. get_export_status until completed
  3. Confirm the destination, text and privacy with the user
  4. publish_to_social with the same export settings. It returns a queued publication
  5. list_social_publications until that destination is completed (read its url) or failed (read its error)

​
publish_to_social

Start a publish to one destination. Returns immediately with a queued publication. One publish per destination runs at a time; starting another while one is queued or running returns a conflict error. Publishing again after one completes creates a second post.
​
string
required
Video ID
​
enum<string>
required
youtube, youtube_shorts, linkedin, x, instagram_post, instagram_reel, instagram_story, facebook_post or facebook_story. The Instagram and Facebook destinations publish through one Facebook connection. See limits
​
string
required
Video title on YouTube. On LinkedIn, X, Instagram and Facebook it is the post text when description is empty. Must not be empty
​
string
YouTube description, or the post text on LinkedIn, X, Instagram and Facebook. Stories show no text
​
enum<string>
public, unlisted or private. Defaults to the most private option the destination offers:
  • youtube, youtube_shorts: private (default), unlisted or public
  • linkedin: private (connections only, default) or public
  • facebook_post: private (only people who manage the Page, default), unlisted (anyone with the link) or public
  • every other destination: public only
​
object
Settings of the completed export to upload, exactly as passed to export_video. Omit for the default export: 1080p, 30 fps, no burned-in subtitles, 1x
​
boolean
YouTube only: upload the transcript as a caption track (default true). Skipped when the export has burned-in subtitles
Facebook destinations post to the default Page set in Settings → Connections, else the first Page the account manages. Instagram destinations likewise post to the default Instagram account. Unlike the app, publish_to_social doesn’t append chapters to a YouTube description; read them with get_chapters and include them in description if you want them.

​
list_social_publications

The latest publish of a video to each destination, including publishes made in the Tella app (TikTok among them). Poll this after publish_to_social.
​
string
required
Video ID
Each publication has:
​
string
One of the publish_to_social destinations, or tiktok
​
enum<string>
queued, running, completed or failed
​
string | null
The post on the destination, once completed
​
string | null
Why a failed publish failed
​
string | null
Set on a completed YouTube publish whose caption track YouTube refused
​
string
The title sent
​
enum<string>
public, unlisted or private, or TikTok’s followers or friends
​
string | null
The platform’s ID for the post
​
string
When the publish started
​
string
When its status last changed

​
Destination limits

Tella checks these before starting a publish and returns a bad_request error naming the rule a video breaks. Lengths are of the export, so a 2x export is half as long. File size is checked after the export, just before uploading, so an oversized export shows up as a failed publication rather than an error on the call.
Last modified on September 30, 2026