API resource
Format
Reformat one finished video for every network it will be posted on. Each platform gets its own MP4 at the size, shape, length and bitrate that network expects (an Instagram Reel at 1080x1920, a YouTube Short or a 1920x1080 video, a Facebook Reel or a 4:5 / 16:9 feed video, X at 720x1280 or 1280x720, LinkedIn at 4:5 or 16:9, ...), H.264 + AAC at 30 fps with fast start, and its own caption written to that network's rules: X's 280 weighted characters, Threads' 500, up to 5 hashtags on Instagram and TikTok, a title and description for YouTube, "link in bio" where links aren't clickable. Send your caption to have it adapted, or leave it out and one is written from what is said in the video. Outputs that come out the same size share one file. Nothing is posted: every finished output has a ready post body for POST /v1/posts. Any active plan.
Format a video
/v1/formatQueues a job; a short video takes about a minute. Up to 2 jobs in progress at once. A video longer than a network allows is trimmed to its limit (the output carries a warning); one shorter than its minimum is skipped. 402 plan_required without a plan.
Body
video_urlstringrequiredThe finished video: an https URL, a med_ id from POST /v1/media, or a TikTok / Reels / YouTube / X link. Up to 60 minutes.
platformsstring[]Any of instagram, tiktok, youtube, facebook, twitter (or x), threads, linkedin. Default: all of them.
captionstringYour caption, adapted to each network. Leave it out to have one written from the video.
titlestringA title for YouTube. Written for you if left out.
notesstringWhat the video is about, the offer, the link to point people to, words to avoid. Steers the captions.
fit"auto" | "blur" | "crop" | "pad"How a frame changes shape. auto (default): crop when the shapes are close, otherwise the whole frame over a blurred copy. blur, crop (fills the frame, trims the edges) or pad (black bars).
captionsbooleanWrite per-platform captions. Default true; false only reformats the video.
curl -X POST "https://creatoros-production-5658.up.railway.app/v1/format" \
-H "Authorization: Bearer $CREATOROS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"video_url": "med_b0Wq7Yx2Rk9LzT4nVs1Pc8Hf3Jd6Gm5Ea2Uo7Ki9Nr0",
"caption": "Stop filming new videos every day. Remix the one you already made! Free guide: https://go.creatoros.ca/guide #contentcreator"
}'{
"job": {
"id": "3c1e8a52-7d4b-4f0e-9a6c-5b2d8e1f7a90",
"platforms": [
"instagram",
"tiktok",
"youtube",
"facebook",
"twitter",
"threads",
"linkedin"
],
"fit": "auto",
"status": "queued",
"step": null,
"ready": 0,
"outputs": [
{
"platform": "instagram",
"status": "queued",
"post": null
}
]
}
}Get a job
/v1/format/{jobId}status: queued, working, done, failed or cancelled. One entry in outputs per platform: status (done, failed or skipped), kind (reel, short, long_video, feed_video or video), size, fit, trimmed, video_url, cover_url, caption, title (YouTube), hashtags, warnings and post: send it as is to POST /v1/posts (add schedule_at or account_ids if you need them).
Path parameters
jobIdstringrequiredThe job id.
curl "https://creatoros-production-5658.up.railway.app/v1/format/3c1e8a52-7d4b-4f0e-9a6c-5b2d8e1f7a90" \
-H "Authorization: Bearer $CREATOROS_API_KEY"{
"job": {
"id": "3c1e8a52-7d4b-4f0e-9a6c-5b2d8e1f7a90",
"status": "done",
"step": "7 of 7 ready",
"ready": 7,
"source": {
"width": 1080,
"height": 1920,
"duration_s": 41.2
},
"outputs": [
{
"platform": "twitter",
"status": "done",
"kind": "video",
"width": 720,
"height": 1280,
"fit": "crop",
"trimmed": false,
"duration_s": 41.2,
"video_url": "https://api.creatoros.ca/v1/media/med_...",
"cover_url": "https://api.creatoros.ca/v1/media/med_...",
"caption": "Stop filming new videos every day. Remix the one you already made! Free guide: https://go.creatoros.ca/guide",
"title": null,
"hashtags": [],
"warnings": [],
"error": null,
"post": {
"platforms": [
"twitter"
],
"post_type": "short_video",
"content": "Stop filming new videos every day. Remix the one you already made! Free guide: https://go.creatoros.ca/guide",
"media": [
"https://api.creatoros.ca/v1/media/med_..."
]
}
},
{
"platform": "linkedin",
"status": "done",
"kind": "video",
"width": 1080,
"height": 1350,
"fit": "blur",
"trimmed": false,
"caption": "Stop filming new videos every day.\n\nRemix the one you already made...",
"hashtags": [
"contentcreator"
],
"warnings": []
}
]
}
}List jobs
/v1/formatNewest first, with access (can_create, and reason when not).
curl "https://creatoros-production-5658.up.railway.app/v1/format" \
-H "Authorization: Bearer $CREATOROS_API_KEY"{
"jobs": [
{
"id": "3c1e8a52-7d4b-4f0e-9a6c-5b2d8e1f7a90",
"status": "working",
"step": "Rendering 2 of 3: 720x1280 for X",
"ready": 5
}
],
"access": {
"plan": "active",
"can_create": true,
"reason": null
},
"platforms": [
"instagram",
"tiktok",
"youtube",
"facebook",
"twitter",
"threads",
"linkedin"
]
}Platform rules
/v1/format/specsWhat Format renders and writes to, per platform: the video variants (kind, width, height, min and max seconds), max_bytes, max_fps, max_kbps, and the caption rules (max_chars, counting: plain or x, hashtags_max, whether links are clickable, title_max).
curl "https://creatoros-production-5658.up.railway.app/v1/format/specs" \
-H "Authorization: Bearer $CREATOROS_API_KEY"{
"platforms": [
{
"platform": "youtube",
"label": "YouTube",
"variants": [
{
"kind": "short",
"width": 1080,
"height": 1920,
"min_s": 1,
"max_s": 180,
"post_type": "short_video"
},
{
"kind": "long_video",
"width": 1920,
"height": 1080,
"min_s": 1,
"max_s": 43200,
"post_type": "long_video"
}
],
"max_bytes": 274877906944,
"max_fps": 30,
"max_kbps": 16000,
"caption": {
"max_chars": 5000,
"counting": "plain",
"hashtags_max": 3,
"links": true,
"title_max": 100
}
}
]
}Cancel a job
/v1/format/{jobId}/cancelStops a queued or running job; finished outputs stay. Delete one with DELETE /v1/format/{jobId}.
Path parameters
jobIdstringrequiredThe job id.
curl -X POST "https://creatoros-production-5658.up.railway.app/v1/format/3c1e8a52-7d4b-4f0e-9a6c-5b2d8e1f7a90/cancel" \
-H "Authorization: Bearer $CREATOROS_API_KEY"{
"ok": true
}