Import your own finished videos
Bring a video made elsewhere into a channel as an episode, then post it from ChannelForge, TikTok's posting screen included. Two REST calls and one upload per file; no credits.
You may already make videos somewhere else: another tool, your own studio, a programme you run yourself. An import brings each finished video into one of your channels as an episode, so it is posted from ChannelForge like the episodes it makes: from TikTok's posting screen (each post yours, as TikTok asks), or on the channel's schedule.
The video is posted as it is. ChannelForge adds nothing to it, and it does not translate, revise or check an imported video again: those are for the episodes it made. An import costs no credits.
How it works#
POST /episodes/import ──▶ one signed upload address per file (for an hour)
│
▼
PUT each file to its address
│
▼
POST /episodes/{id}/finish-import ──▶ the episode is ready ──▶ post itYour key needs the write scope (Settings → API & webhooks → Keys). Until the import is finished the episode is held, with "Importing" as its reason: nothing posts it.
1. Start the import#
Send the video's title, its words, its length and each file's size in bytes. external_id is your own id for the video: the same one again in the same channel is the same episode, never a second one, so a retry is always safe.
curl -s -X POST $FORGE_API/episodes/import \
-H "Authorization: Bearer $FORGE_KEY" -H "Content-Type: application/json" \
-d '{
"channel_id": "ch_…",
"external_id": "2026-11-04-standing-on-titan",
"title": "Standing on Titan (−179 °C)",
"caption": "Your breath would freeze mid-air",
"hashtags": ["#space", "#saturn"],
"duration_s": 152.4,
"cover_s": 84.5,
"edit_segments": [[0, 6.2], [18.4, 43.4], [57.2, 90.4]],
"files": {"video": {"bytes": 41234567}, "edit": {"bytes": 20345678}, "thumb": {"bytes": 345678}}
}'{
"episode_id": "ep_…", "state": "importing", "already": false,
"uploads": [
{"file": "video", "name": "video.mp4", "bytes": 41234567, "method": "PUT", "url": "https://…", "headers": {"Content-Type": "video/mp4"}, "expires_in": 3600},
{"file": "edit", "name": "video-fb.mp4", "bytes": 20345678, "method": "PUT", "url": "https://…", "headers": {"Content-Type": "video/mp4"}, "expires_in": 3600},
{"file": "thumb", "name": "thumb.jpg", "bytes": 345678, "method": "PUT", "url": "https://…", "headers": {"Content-Type": "image/jpeg"}, "expires_in": 3600}
],
"finish": "/api/v1/episodes/ep_…/finish-import"
}| Field | Needed | What it is |
|---|---|---|
channel_id | yes | the channel it goes to |
external_id | yes | your own id: letters, digits, dots, dashes or underscores, at most 100 |
title | yes | at most 200 characters |
duration_s | yes | the video's length, 3 to 600 seconds |
files.video | yes | the whole video, an MP4 of up to 500 MB |
files.edit | no | a version of at most 89 seconds, for an account that may not post the whole video |
files.thumb | no | its cover, a JPEG of up to 5 MB |
caption | no | the post's opening line |
hashtags | no | up to 15 |
cover_s | no | the moment of the video that is its cover, in seconds |
edit_segments | no | the pieces of the video the edit keeps, [start, end] in seconds |
language | no | a language code such as en or pt-BR; the channel's own without it |
A TikTok caption starts from your title, your opening line and the channel's hashtags, and you can change it on the posting screen. TikTok's cover is the frame at cover_s, taken from the edit's own timeline when the edit is the file that is posted: that is what edit_segments is for.
2. Send the files#
PUT each file to its address with the Content-Type given. The addresses go straight to your workspace's storage and last an hour; starting the same import again signs them anew.
curl -s -X PUT -H "Content-Type: video/mp4" --upload-file video.mp4 "<the video's url>"
curl -s -X PUT -H "Content-Type: video/mp4" --upload-file video-fb.mp4 "<the edit's url>"
curl -s -X PUT -H "Content-Type: image/jpeg" --upload-file thumb.jpg "<the cover's url>"3. Finish#
curl -s -X POST $FORGE_API/episodes/ep_…/finish-import -H "Authorization: Bearer $FORGE_KEY"{"episode_id": "ep_…", "state": "ready", "already": false, "links": {"episode": "https://…/episodes/ep_…", "tiktok": "https://…/episodes/ep_…/tiktok"}}Each file is checked first: it is there, its size is the one you said, and it is an MP4 or a JPEG. Until then the answer is 409 with what is missing, such as "edit (video-fb.mp4) has not arrived". Once the episode is ready, the episode.ready webhook is sent with "imported": true. Finishing it again answers already.
Import by address#
Where import by URL is switched on for your workspace, a file can be given by its address instead of its size, and ChannelForge fetches it itself: no upload step. Send rights_confirmed: true with it, to confirm you own the files or have the rights to post them.
{
"channel_id": "ch_…", "external_id": "2026-11-04-standing-on-titan", "title": "Standing on Titan (−179 °C)",
"duration_s": 152.4, "rights_confirmed": true,
"files": {"video": {"url": "https://drive.google.com/file/d/…/view"}, "thumb": {"url": "https://example.org/titan.jpg"}}
}The answer names the job that fetches them (fetching.job_id; GET /jobs/{id} follows it). When every file comes by address, the job finishes the import itself and episode.ready is sent; when some are uploaded too, finish as above once your uploads are in.
- Only public
httpsaddresses are fetched; every redirect is checked again, and nothing on a private network is reached. - Each file is checked from its own first bytes (an MP4, a JPEG) and has the same size limits as an upload.
- Google Drive and Dropbox share links work as they are: the file must be shared with "anyone with the link".
- An address that answers with an error, too big a file or the wrong kind of file fails the job with the reason; the same
external_idagain tries once more.
Posting it#
Open the episode from its link. The Publishing card on its Post tab lists the platforms its channel is connected to. For TikTok, Post… opens TikTok's screen, where you choose who sees the post and agree to TikTok's terms, every time. A channel whose schedule is on posts its imported episodes in their turn, like any other.
The import screen#
Where your workspace has it, the same three steps have a screen of their own, with no code: open a channel's Distribution tab and press Import videos, or go to Import under the workspace. Drop several MP4 files at once — and a JPEG with the same name as a video, as its cover. Each file is uploaded straight from your browser to your workspace's storage, two at a time, then finished as a ready short of the channel. A file's own name and size are its external_id, so the same file dropped again is the same episode, never a second one. You confirm, once per batch, that you hold the rights to post the videos. The screen takes up to 20 files at a time, within the limits below.
Limits#
- 60 imports a day per workspace, counted over the last 24 hours (
429with the codelimitpast that). - The video up to 500 MB and 10 minutes; the cover up to 5 MB.
- Everything else as for any request: 120 a minute per key.
Related#
- REST API reference — the import's fields and answers.
- Using the API: a walk-through — the episodes ChannelForge makes, from a key to a post.
- Webhooks and REST hooks —
episode.readyand the rest.
Something missing or unclear? Tell us and we will improve this page.