--- title: "Publish a video to social media" method: POST path: "/v1/videos/{id}/publish" tags: ["Videos"] --- # Publish a video to social media `POST /v1/videos/{id}/publish` ## Request - Base URL: `https://api.tella.com` - URL: `https://api.tella.com/v1/videos/{id}/publish` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Posts the video to one of your connected social accounts: YouTube, YouTube Shorts, LinkedIn, X, Instagram (post, reel or story) or Facebook (post or story). This posts under your own account, so check the destination, text and privacy before calling it. It uploads an export with the `export` settings, reusing a finished or running one or starting one, so there is no need to export first. The account must already be connected in Tella (Settings → Connections, or Share → Publish in the editor); a 403 means it isn't, or that the plan doesn't include the export's resolution or frame rate. With several accounts connected for a destination, pass `accountId` from GET /v1/social-accounts; without it the oldest connected one posts. To post to several accounts, call once per account. TikTok can only be published from the Tella app, because TikTok requires its consent form. Returns 202 with a `queued` publication, which stays `queued` while the export renders; poll GET /v1/videos/{id}/publish for the result. To post later, pass `scheduledAt`: the publication stays `queued` with that `scheduledAt` until then, and DELETE /v1/videos/{id}/publish cancels it before it goes out. One publish per destination and account runs at a time. Requires edit access to the video. ## Path parameters - `id` string, required: Unique video identifier ## Request body - PublishVideoRequest - `accountId` string: Which of your connected accounts to post with, from GET /v1/social-accounts. Defaults to the oldest connected account for the destination. - `description` string: YouTube description, or the post text on LinkedIn, X, Instagram and Facebook. - `destination` 'youtube' | 'youtube_shorts' | 'linkedin' | 'x' | 'instagram_post' | 'instagram_reel' | 'instagram_story' | 'facebook_post' | 'facebook_story' | 'facebook_reel', required: Where to post. YouTube Shorts must be vertical or square and at most 3 minutes; Facebook Stories vertical and at most 60 seconds; Facebook Reels vertical and at most 90 seconds; Instagram Stories at most 60 seconds and 100 MB; Instagram posts and reels at most 15 minutes and 300 MB; no Instagram destination takes a 4K export; LinkedIn at most 30 minutes and 500 MB. Instagram, Facebook Stories and Reels and LinkedIn need at least 3 seconds. YouTube takes at most 15 minutes from a channel that isn't verified; X at most 20 minutes, or 125 with Premium or a checkmark. Stories show no text. The Facebook and Instagram destinations publish through one Facebook connection. - `export` object: Settings of the export to upload, as POST /v1/videos/{id}/exports takes them. A finished or running export with these settings is reused; otherwise one is started. Defaults to 1080p, 30 fps, no burned-in subtitles, 1x. - `fps` '30' | '60' - `resolution` '4k' - `speed` '1' | '2' | '0.5' | '0.75' | '0.8' | '0.9' | '1.1' | '1.2' | '1.25' | '1.3' | '1.35' | '1.5' | '1.7' | '1.75' | '2.5' - `subtitles` boolean - `privacy` 'public' | 'unlisted' | 'private': YouTube: private (default), unlisted or public. LinkedIn: private (connections only, default) or public. Facebook posts: private (only people who manage the Page, default), unlisted (anyone with the link) or public. Facebook posts, stories and reels go to the default Page set in Settings → Connections, else the first Page the account manages. Instagram destinations likewise go to the default Instagram account. Every other destination: public only. - `scheduledAt` string: When to post, as an ISO 8601 time with a timezone, e.g. 2026-10-20T15:00:00Z; at most 30 days ahead. The video is exported now, so later edits aren't in the post. Omit to post as soon as the export is ready. - `title` string, required: Video title on YouTube. On LinkedIn, X, Instagram and Facebook it is the post text when description is empty. - `trialReel` 'manual' | 'performance': Instagram Reels only: share it as a trial reel, shown to people who don't follow the account first. manual: it stays a trial until the user shares it with followers in the Instagram app. performance: Instagram shares it with followers if it performs well. Omit for an ordinary reel. - `uploadCaptions` boolean: YouTube only: upload the transcript as a caption track (default true). Skipped when the export has burned-in subtitles. ## Response `202` Publish queued - PublishVideoResponse - `publication` Publication, required - `accountId` string, nullable, required: The connected account it was published with; null for publishes made before Tella supported several accounts - `accountName` string, nullable, required: That account's name in Tella - `captionsError` string, nullable, required: Set on a completed YouTube publish whose caption track was refused - `createdAt` string, required - `destination` string, required: One of the request destinations, or tiktok - `error` string, nullable, required: Why a failed publish failed and what to do next, as a sentence for people. Never the destination's raw response - `privacy` 'public' | 'unlisted' | 'private' | 'followers' | 'friends', required - `providerVideoId` string, nullable, required - `scheduledAt` string, nullable, required: When a scheduled publish goes out; null when it wasn't scheduled - `status` 'queued' | 'running' | 'completed' | 'failed' | 'cancelled', required: A scheduled publish stays `queued` until its time, and is `cancelled` if taken back before then - `title` string, required - `updatedAt` string, required - `url` string, nullable, required: The post on the destination, once completed ## Other responses - `400`: The request was malformed or contained invalid parameters. - `401`: Authentication is required. Provide a valid API key. - `403`: You don't have permission to access this resource. - `404`: The requested resource was not found. - `409`: The request conflicts with the resource's current state, e.g. an Idempotency-Key whose first request is still in progress. Retry once it settles. - `429`: You have exceeded the rate limit. Please slow down. - `500`: An unexpected error occurred - `501`: The requested operation is not implemented. - `503`: A dependency was unavailable and the request was not executed. Safe to resend unchanged after the Retry-After delay. ## Changes > 66 revisions in range; 1 not diffed. - **2026-11-08** `a15e5c06bd15`: 1 info - added the new optional request property `trialReel` - **2026-11-07** `0cc3fcd307ad`: 9 info - added the new `0.8` enum value to the request property `export/speed` - added the new `0.9` enum value to the request property `export/speed` - added the new `1.1` enum value to the request property `export/speed` - added the new `1.2` enum value to the request property `export/speed` - …5 more - **2026-10-27** `532e8ffc27eb`: 5 info - added the new `facebook_post` enum value to the request property `destination` - added the new `facebook_story` enum value to the request property `destination` - added the new `instagram_post` enum value to the request property `destination` - added the new `instagram_reel` enum value to the request property `destination` - …1 more - **2026-10-15** `12b6eccbb321`: 1 warning, 2 info - added the new `cancelled` enum value to the `publication/status` response property for the response status `202` - added the new optional request property `scheduledAt` - added the required property `publication/scheduledAt` to the response with the `202` status - **2026-10-09** `9773130bbc2b`: 3 info - added the new optional request property `accountId` - added the required property `publication/accountId` to the response with the `202` status - added the required property `publication/accountName` to the response with the `202` status [Operation history](https://skmtc.dev/withchima/apis/tella-public-api/changes/v1/videos/:id/publish/post.md) --- [API](https://skmtc.dev/withchima/apis/tella-public-api.md) - [All operations](https://skmtc.dev/withchima/apis/tella-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/withchima/apis/tella-public-api/revisions/a15e5c06bd15?raw)