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

POST/v1/format

Queues 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_urlstringrequired

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

captionstring

Your caption, adapted to each network. Leave it out to have one written from the video.

titlestring

A title for YouTube. Written for you if left out.

notesstring

What 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).

captionsboolean

Write 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"
  }'
Response 201
{
  "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

GET/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

jobIdstringrequired

The job id.

curl "https://creatoros-production-5658.up.railway.app/v1/format/3c1e8a52-7d4b-4f0e-9a6c-5b2d8e1f7a90" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "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

GET/v1/format

Newest 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"
Response 200
{
  "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

GET/v1/format/specs

What 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"
Response 200
{
  "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

POST/v1/format/{jobId}/cancel

Stops a queued or running job; finished outputs stay. Delete one with DELETE /v1/format/{jobId}.

Path parameters

jobIdstringrequired

The 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"
Response 200
{
  "ok": true
}