curl -X POST https://api.shortkit.dev/v1/content/images \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  -F 'metadata={
    "title": "Spring drop hero",
    "externalId": "post-98765",
    "customMetadata": {"productId": "SKU-12345"},
    "images": [
      {"file": "hero", "altText": "Red sneaker"},
      {"sourceUrl": "https://cdn.example.com/spring/side.jpg", "altText": "Side view"}
    ]
  };type=application/json' \
  -F [email protected]

import json
import requests

metadata = {
    "title": "Spring drop hero",
    "externalId": "post-98765",
    "customMetadata": {"productId": "SKU-12345"},
    "images": [
        {"file": "hero", "altText": "Red sneaker"},
        {"sourceUrl": "https://cdn.example.com/spring/side.jpg", "altText": "Side view"},
    ],
}

with open("hero.jpg", "rb") as hero:
    resp = requests.post(
        "https://api.shortkit.dev/v1/content/images",
        headers={"Authorization": "Bearer sk_live_your_secret_key"},
        files={
            "metadata": (None, json.dumps(metadata), "application/json"),
            "hero": ("hero.jpg", hero, "image/jpeg"),
        },
    )

carousel = resp.json()["data"]

import { readFile } from "fs/promises";

const form = new FormData();
form.append("metadata", JSON.stringify({
  title: "Spring drop hero",
  externalId: "post-98765",
  customMetadata: { productId: "SKU-12345" },
  images: [
    { file: "hero", altText: "Red sneaker" },
    { sourceUrl: "https://cdn.example.com/spring/side.jpg", altText: "Side view" },
  ],
}));
form.append("hero", new Blob([await readFile("hero.jpg")], { type: "image/jpeg" }), "hero.jpg");

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

const { data: carousel } = await response.json();

{
  "data": {
    "id": "3f2a9c1e-7b4d-4e8a-9f10-2c6d8e1b5a77",
    "externalId": "post-98765",
    "contentType": "carousel",
    "status": "ready",
    "publishStatus": "published",
    "title": "Spring drop hero",
    "description": null,
    "tags": [],
    "customMetadata": {"productId": "SKU-12345"},
    "section": null,
    "author": null,
    "protected": false,
    "images": [
      {
        "id": "b50322db-20dd-47b2-be24-2fb7e3c2b279",
        "position": 0,
        "imageUrl": "https://image.media.shortkit.dev/carousels/5b85b33b78c048ca.jpg",
        "altText": "Red sneaker"
      },
      {
        "id": "e1c8a7f2-9d3b-4c56-8a01-7f2e6b9d4c33",
        "position": 1,
        "imageUrl": "https://image.media.shortkit.dev/carousels/bfd496b145d5416a.jpg",
        "altText": "Side view"
      }
    ],
    "replayed": false,
    "createdAt": "2026-10-27T18:58:09.541869+00:00"
  },
  "meta": {
    "request_id": "req_09eeb351006b"
  }
}

{
  "data": null,
  "meta": {
    "request_id": "req_5c852d7559cc"
  },
  "errors": [
    {
      "code": "invalid_images",
      "message": "1 of 2 images could not be used; nothing was created",
      "details": [
        {
          "position": 1,
          "code": "unsupported_image",
          "message": "File is not a supported image (JPEG, PNG, WebP or GIF)"
        }
      ]
    }
  ]
}