Media

Upload a file

POST /v1/media takes the raw file as the request body. Set Content-Type to the file's type.

curl https://ugcapi.dev/v1/media \
  -H "Authorization: Bearer ugc_live_..." \
  -H "Content-Type: video/mp4" \
  --data-binary @clip.mp4

import { readFile } from "node:fs/promises";

const res = await fetch("https://ugcapi.dev/v1/media", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.UGCAPI_KEY,
    "Content-Type": "image/jpeg",
  },
  body: await readFile("slide-1.jpg"),
});
const { url } = await res.json();

The response is { "url": "..." }. Put that URL in a post's media array. Upload slideshow images one call per image, in order.

Using your own URLs

Any URL that returns the file directly over HTTPS works: a public bucket, a CDN, a signed URL valid long enough to cover the scheduled time. Platforms fetch media when the post publishes, so the URL must still work then. Pages that show a file, like a Google Drive share page, don't work.

Retention

We keep uploaded files until 3 days after the last post that uses them, then delete them. A file used by a post scheduled for next month stays until 3 days after that post. Don't use upload URLs as permanent hosting.

Formats that work on every platform

If you design slides at 9:16 and also post a carousel, keep text inside the center 4:5 area, since carousels are cropped to 4:5. See formats and options.

Errors

• invalid_request: empty body or missing Content-Type on upload.
• media_unreachable: we or the platform couldn't download a URL in your post. Check that it is public and returns the file itself.
• platform_rejected: the platform refused the file, for example a duration or codec it doesn't accept. The message has the platform's reason.

Full list in errors. Duration and size limits per platform are in limits.