Skip to content
Browse the docs

Docs / Developers

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 it

Your 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.

bash
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}}
  }'
json
{
  "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"
}
FieldNeededWhat it is
channel_idyesthe channel it goes to
external_idyesyour own id: letters, digits, dots, dashes or underscores, at most 100
titleyesat most 200 characters
duration_syesthe video's length, 3 to 600 seconds
files.videoyesthe whole video, an MP4 of up to 500 MB
files.editnoa version of at most 89 seconds, for an account that may not post the whole video
files.thumbnoits cover, a JPEG of up to 5 MB
captionnothe post's opening line
hashtagsnoup to 15
cover_snothe moment of the video that is its cover, in seconds
edit_segmentsnothe pieces of the video the edit keeps, [start, end] in seconds
languagenoa 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.

bash
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#

bash
curl -s -X POST $FORGE_API/episodes/ep_…/finish-import -H "Authorization: Bearer $FORGE_KEY"
json
{"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.

json
{
  "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 https addresses 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_id again 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 (429 with the code limit past 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.

Something missing or unclear? Tell us and we will improve this page.