Upload Content

ShortKit supports two content types — videos and carousels — each with a distinct upload path. Videos go through an asynchronous processing pipeline (transcoding, caption generation, search indexing). Carousels are ready immediately.

Video upload workflow

A video upload follows a simple flow: create the upload session, PUT the file to the signed URL, and poll until processing completes.

Create an upload session

cURL
Python
Node.js

curl -X POST https://api.shortkit.dev/v1/content/upload \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "contentType": "video",
    "title": "Product Launch Teaser",
    "description": "30-second preview of the new lineup",
    "tags": ["product", "launch"],
    "customMetadata": {
      "campaignId": "spring-2026"
    }
  }'

import requests

resp = requests.post(
    "https://api.shortkit.dev/v1/content/upload",
    headers={
        "Authorization": "Bearer sk_live_your_secret_key",
        "Content-Type": "application/json",
    },
    json={
        "contentType": "video",
        "title": "Product Launch Teaser",
        "description": "30-second preview of the new lineup",
        "tags": ["product", "launch"],
        "customMetadata": {"campaignId": "spring-2026"},
    },
)

data = resp.json()["data"]
content_id = data["id"]
upload_url = data["uploadUrl"]

const response = await fetch("https://api.shortkit.dev/v1/content/upload", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_live_your_secret_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    contentType: "video",
    title: "Product Launch Teaser",
    description: "30-second preview of the new lineup",
    tags: ["product", "launch"],
    customMetadata: { campaignId: "spring-2026" },
  }),
});

const { data } = await response.json();
const { id: contentId, uploadUrl } = data;

Field	Type	Required	Default	Notes
`title`	string	Yes	—	Max 200 characters
`description`	string	No	`null`	Max 2000 characters
`tags`	string[]	No	`[]`
`customMetadata`	object	No	`{}`	Arbitrary key-value pairs passed through to the SDK
`section`	string	No	`null`	Grouping label for filtering
`author`	string	No	`null`	Author name

The response contains the content id and a signed uploadUrl:

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "uploadUrl": "https://storage.shortkit.dev/uploads/...",
    "status": "waiting_for_upload",
    "title": "Product Launch Teaser",
    "tags": ["product", "launch"],
    "customMetadata": { "campaignId": "spring-2026" },
    "createdAt": "2026-03-02T12:00:00+00:00"
  }
}

The POST create response uses the field name status, while the status-polling GET response uses uploadStatus. Both hold the same upload_status values; the field-name difference is a known API quirk we plan to reconcile.

Upload the video file

PUT the raw video bytes to the signed URL. This goes directly to storage — it does not pass through the ShortKit API.

cURL
Python
Node.js

curl -X PUT "${uploadUrl}" \
  -H "Content-Type: video/mp4" \
  --data-binary @video.mp4

with open("video.mp4", "rb") as f:
    requests.put(
        upload_url,
        headers={"Content-Type": "video/mp4"},
        data=f,
    )

import { readFileSync } from "fs";

await fetch(uploadUrl, {
  method: "PUT",
  headers: { "Content-Type": "video/mp4" },
  body: readFileSync("video.mp4"),
});

Once the file lands, processing starts automatically. The video is encoded and the content status moves from waiting_for_upload to processing. When encoding completes, the status transitions to ready and the content becomes eligible for the feed. A caption track and spoken language detection are also generated automatically — these typically complete within a few minutes after the video reaches ready status. The detected language is stored as customMetadata.language (BCP 47 code, e.g. "en", "es", "ja").

iOS-recorded video

When the video was captured on an iOS device, include "origin": "ios_upload" in the upload request. iOS HEVC recordings frequently ship without explicit color metadata, and standard thumbnail extraction can produce wrong-color first frames under that condition. Marking the origin enables color-accurate thumbnail generation.

{
  "contentType": "video",
  "origin": "ios_upload",
  "title": "Product demo"
}

Safe to set unconditionally in your iOS upload flow; harmless for properly-tagged videos. To retroactively mark existing content that was uploaded without the origin field, use PATCH /v1/content/:id with { "origin": "ios_upload" }. Thumbnail re-extraction is triggered automatically for eligible content. If you render this content in a custom feed via the SDK, also set origin: .iosUpload (iOS) or 'ios_upload' (React Native) on the matching FeedInput.video so the client fetches the color-corrected thumbnail. See Custom feed input.

Poll for status

Check processing progress with the upload status endpoint:

cURL
Python
Node.js

curl https://api.shortkit.dev/v1/content/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer sk_live_your_secret_key"

import time

while True:
    resp = requests.get(
        f"https://api.shortkit.dev/v1/content/{content_id}",
        headers={"Authorization": "Bearer sk_live_your_secret_key"},
    )
    status = resp.json()["data"]["uploadStatus"]
    print(f"Status: {status}")

    if status in ("ready", "errored"):
        break
    time.sleep(5)

async function pollUntilReady(contentId) {
  while (true) {
    const resp = await fetch(
      `https://api.shortkit.dev/v1/content/${contentId}`,
      { headers: { "Authorization": "Bearer sk_live_your_secret_key" } }
    );
    const { data } = await resp.json();
    console.log(`Status: ${data.uploadStatus}`);

    if (data.uploadStatus === "ready" || data.uploadStatus === "errored") return data;
    await new Promise((r) => setTimeout(r, 5000));
  }
}

When the status reaches ready, the response includes the playbackId and duration. The SDK uses the playback ID to resolve streaming and thumbnail URLs.

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "uploadStatus": "ready",
    "title": "Product Launch Teaser",
    "duration": 32.5,
    "playbackId": "rJ4OE02Z0Z4IY01Eo4Vgup5OilG8xZB9"
  }
}

The content now appears in the feed (GET /v1/feed), subject to scheduling and editorial controls.

Use a webhook callback

As an alternative to polling, pass callbackUrl in the upload request to receive push notifications as the video moves through the pipeline.

cURL
Python
Node.js

curl -X POST https://api.shortkit.dev/v1/content/upload \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "contentType": "video",
    "title": "Product Launch Teaser",
    "callbackUrl": "https://your-backend.com/webhooks/shortkit"
  }'

resp = requests.post(
    "https://api.shortkit.dev/v1/content/upload",
    headers={
        "Authorization": "Bearer sk_live_your_secret_key",
        "Content-Type": "application/json",
    },
    json={
        "contentType": "video",
        "title": "Product Launch Teaser",
        "callbackUrl": "https://your-backend.com/webhooks/shortkit",
    },
)

const resp = await fetch("https://api.shortkit.dev/v1/content/upload", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_live_your_secret_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    contentType: "video",
    title: "Product Launch Teaser",
    callbackUrl: "https://your-backend.com/webhooks/shortkit",
  }),
});

ShortKit will POST to your endpoint at each stage of processing:

content.imported / status: "processing" — Sent when your file is received and processing begins. Contains the playbackId.
content.imported / status: "ready" — Sent when transcoding completes and all quality levels are available.
content.import_failed / status: "error" — Sent if processing fails.

See Callback events for full payload shapes and retry behavior.

Carousel creation workflow

Carousels skip the processing pipeline entirely. They are ready the moment you create them.

Create the carousel

cURL
Python
Node.js

curl -X POST https://api.shortkit.dev/v1/content \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "contentType": "carousel",
    "title": "Spring Collection",
    "description": "Preview our new arrivals",
    "tags": ["fashion", "spring"],
    "caption": "Swipe to explore the collection",
    "autoScrollInterval": 5.0,
    "section": "Style",
    "author": "Editorial Team"
  }'

resp = requests.post(
    "https://api.shortkit.dev/v1/content",
    headers={
        "Authorization": "Bearer sk_live_your_secret_key",
        "Content-Type": "application/json",
    },
    json={
        "contentType": "carousel",
        "title": "Spring Collection",
        "description": "Preview our new arrivals",
        "tags": ["fashion", "spring"],
        "caption": "Swipe to explore the collection",
        "autoScrollInterval": 5.0,
        "section": "Style",
        "author": "Editorial Team",
    },
)

carousel_id = resp.json()["data"]["id"]

const response = await fetch("https://api.shortkit.dev/v1/content", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_live_your_secret_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    contentType: "carousel",
    title: "Spring Collection",
    description: "Preview our new arrivals",
    tags: ["fashion", "spring"],
    caption: "Swipe to explore the collection",
    autoScrollInterval: 5.0,
    section: "Style",
    author: "Editorial Team",
  }),
});

const { data } = await response.json();
const carouselId = data.id;

Field	Type	Required	Default	Notes
`contentType`	string	Yes	`"video"`	Must be `"carousel"`
`title`	string	Yes	—	Max 200 characters
`caption`	string	No	`null`	Text displayed below images (max 500 characters)
`autoScrollInterval`	float	No	`null`	Seconds between auto-scroll; `null` for manual swiping only
`pinPosition`	integer	No	`null`	Pin to a specific feed position
`publishAt`	string	No	`null`	ISO-8601 datetime; hides from feed until this time
`expiresAt`	string	No	`null`	ISO-8601 datetime; auto-archives after this time

The response comes back with status: "ready" immediately. No polling needed.

Upload images

Add images one at a time using multipart form data. Each carousel supports up to 10 images.

cURL
Python
Node.js

curl -X POST "https://api.shortkit.dev/v1/content/${carouselId}/images" \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  -F "[email protected]" \
  -F "position=0" \
  -F "altText=Model wearing spring jacket"

for i, (filename, alt) in enumerate([
    ("photo1.jpg", "Model wearing spring jacket"),
    ("photo2.jpg", "Close-up of fabric texture"),
    ("photo3.jpg", "Full outfit on runway"),
]):
    with open(filename, "rb") as f:
        requests.post(
            f"https://api.shortkit.dev/v1/content/{carousel_id}/images",
            headers={"Authorization": "Bearer sk_live_your_secret_key"},
            files={"file": (filename, f, "image/jpeg")},
            data={"position": i, "altText": alt},
        )

import { createReadStream } from "fs";

const images = [
  { file: "photo1.jpg", alt: "Model wearing spring jacket" },
  { file: "photo2.jpg", alt: "Close-up of fabric texture" },
  { file: "photo3.jpg", alt: "Full outfit on runway" },
];

for (let i = 0; i < images.length; i++) {
  const form = new FormData();
  form.append("file", createReadStream(images[i].file));
  form.append("position", i.toString());
  form.append("altText", images[i].alt);

  await fetch(
    `https://api.shortkit.dev/v1/content/${carouselId}/images`,
    {
      method: "POST",
      headers: { "Authorization": "Bearer sk_live_your_secret_key" },
      body: form,
    }
  );
}

Field	Type	Required	Default	Notes
`file`	File	Yes	—	JPEG, PNG, or WebP
`position`	integer	No	`0`	0-based position in the carousel
`altText`	string	No	`null`	Accessibility description

Reorder images

Pass all image IDs in the desired order. Each image’s position is set to its index in the array.

curl -X PUT "https://api.shortkit.dev/v1/content/${carouselId}/images/order" \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "imageIds": ["img-uuid-3", "img-uuid-1", "img-uuid-2"]
  }'

The carousel’s thumbnail in feed responses is automatically set to the first image (position 0).

Post-creation management

These operations apply to both videos and carousels.

Update metadata

Use PATCH /v1/content/{contentId} to update any metadata field after creation. All fields are optional — only include the ones you want to change.

curl -X PATCH "https://api.shortkit.dev/v1/content/${contentId}" \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Title",
    "tags": ["breaking", "politics"],
    "section": "Politics",
    "publishAt": "2026-03-05T09:00:00Z",
    "expiresAt": "2026-04-05T09:00:00Z",
    "customMetadata": {
      "campaignId": "updated-123",
      "newField": "added",
      "obsoleteField": null
    }
  }'

customMetadata uses shallow merge semantics: new keys are added, existing keys are overwritten, and keys set to null are removed. Other fields are replaced outright.

Add captions

Upload a VTT or SRT caption file for video content:

cURL
Python

curl -X POST "https://api.shortkit.dev/v1/content/${contentId}/captions" \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  -F "[email protected]" \
  -F "language=es" \
  -F "label=Spanish"

with open("subtitles-es.vtt", "rb") as f:
    requests.post(
        f"https://api.shortkit.dev/v1/content/{content_id}/captions",
        headers={"Authorization": "Bearer sk_live_your_secret_key"},
        files={"file": ("subtitles-es.vtt", f, "text/vtt")},
        data={"language": "es", "label": "Spanish"},
    )

Field	Type	Required	Default	Notes
`file`	File	Yes	—	`.vtt` or `.srt` file
`language`	string	No	`"en"`	BCP-47 language code
`label`	string	No	`"English"`	Human-readable label shown in the player

External captions are immediately ready — no processing delay. They appear alongside any auto-generated tracks in feed responses and the SDK renders them automatically.

Add publication URLs

Attach external links to content (e.g., the source article, a product page). The first URL (position 0) is surfaced as publisherUrl in the feed.

curl -X POST "https://api.shortkit.dev/v1/content/${contentId}/publication-urls" \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/article/spring-launch",
    "label": "Read the full article",
    "position": 0
  }'

Update, reorder, or delete publication URLs with PUT /v1/content/{id}/publication-urls/{urlId}, PUT /v1/content/{id}/publication-urls/order, and DELETE /v1/content/{id}/publication-urls/{urlId}.

Archive content

Soft-delete content by sending a DELETE. The content is set to archived status and removed from all feeds, but the record is preserved.

curl -X DELETE "https://api.shortkit.dev/v1/content/${contentId}" \
  -H "Authorization: Bearer sk_live_your_secret_key"

Get Started

Content

Display

Build Your Experience

Users & Data

Video upload workflow

Create an upload session

Upload the video file

iOS-recorded video

Poll for status

Use a webhook callback

Carousel creation workflow

Create the carousel

Upload images

Reorder images

Post-creation management

Update metadata

Add captions

Add publication URLs

Archive content

​Video upload workflow

​Create an upload session

​Upload the video file

​iOS-recorded video

​Poll for status

​Use a webhook callback

​Carousel creation workflow

​Create the carousel

​Upload images

​Reorder images

​Post-creation management

​Update metadata

​Add captions

​Add publication URLs

​Archive content

Video upload workflow

Create an upload session

Upload the video file

iOS-recorded video

Poll for status

Use a webhook callback

Carousel creation workflow

Create the carousel

Upload images

Reorder images

Post-creation management

Update metadata

Add captions

Add publication URLs

Archive content