Media

How do I attach an image or a video?

Two ways, and you can mix them in the same post. Give Chirpie a public URL and it fetches the file for you, or upload the file itself and attach the id it gives back. Either way the same per-platform rules apply, and anything the target platform cannot accept is refused before the post goes out.

POST /api/v1/media
Authorization: Bearer chirpie_sk_YOUR_KEY
Content-Type: multipart/form-data

Both delivery models end up in the same media field on a post:

{
  "account_id": "550e8400-e29b-41d4-a716-446655440000",
  "text": "Two pictures, one posted from a file and one from a link.",
  "media": [
    { "id": "7c3f1a2b-4d5e-6f70-8192-a3b4c5d6e7f8", "alt": "A bird on a branch" },
    { "url": "https://example.com/second.png", "alt": "The same bird, closer" }
  ]
}

Upload a file

POST /api/v1/media
Authorization: Bearer chirpie_sk_YOUR_KEY
Idempotency-Key: upload-hero-2026-11-01
Content-Type: multipart/form-data

An optional Idempotency-Key makes a retry of the upload safe: the same key with the same request replays the original response for 24 hours rather than storing a second copy, and the replay carries Idempotent-Replay: true. Max 255 characters. See Idempotency.

Send the file as a part named file. The file type is read from the file's own first bytes, never from its name or the content type you declare, so a mislabelled file is refused rather than published.

Request Body

You can also send a JSON body, which is what a client that cannot build a multipart request uses. Name either a public URL or the bytes themselves:

Every shape is validated identically: the type is read from the file's own bytes, so base64 is not a way past the checks a file part gets.

Base64 costs a third in transit, so that form carries 3 MB of file where a file part carries 4 MB. A url is not an upload, so neither of those applies: Chirpie fetches it, up to 20 MB for an image and 512 MB for a video, and the target platform's own limit applies on top when you attach it to a post.

Example

curl -X POST https://chirpie.ai/api/v1/media \
  -H "Authorization: Bearer chirpie_sk_YOUR_KEY" \
  -F "file=@./screenshot.png"

Response 201 Created

{
  "data": {
    "id": "7c3f1a2b-4d5e-6f70-8192-a3b4c5d6e7f8",
    "url": "https://blob.chirpie.ai/media/.../7c3f1a2b.png",
    "mime_type": "image/png",
    "media_type": "image",
    "bytes": 184320,
    "width": 1200,
    "height": 630,
    "filename": "screenshot.png",
    "created_at": "2026-04-01T13:55:00.000Z",
    "expires_at": "2026-04-08T13:55:00.000Z"
  }
}

Error Responses

Attach media to a post

Every endpoint that takes media takes the same three fields, and you use one of them, not several:

media_urls is unchanged and keeps working. Sending two of the three is refused with 400 bad_request, because they are three spellings of one field and there is no single answer to what is attached.

These work identically on POST /api/v1/posts, each part of POST /api/v1/threads, and PATCH /api/v1/posts/:id.

Example

curl -X POST https://chirpie.ai/api/v1/posts \
  -H "Authorization: Bearer chirpie_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "550e8400-e29b-41d4-a716-446655440000",
    "text": "Shipping new features today!",
    "media": [
      { "id": "7c3f1a2b-4d5e-6f70-8192-a3b4c5d6e7f8", "alt": "The new dashboard" }
    ]
  }'

Error Responses

Alt text

Alt text describes an image or a video for people using a screen reader. Put it on the media item:

{ "media": [{ "url": "https://example.com/chart.png", "alt": "Revenue doubled in Q1" }] }

Chirpie sends it to every platform that stores one, and sends nothing when you leave it out. A description is never invented for you.

Which delivery model should I use?

Uploading is also what the CLI, the SDK and the MCP server use when you hand them a local file, so chirpie post --media ./shot.png needs nothing else from you.