Docs/Uploads

Uploads

Upload media; shared by the Publishing and Social APIs.

Start Upload

POSThttps://api.fountain.fm/v1/uploads

Start a media upload. Returns presigned URLs (one per part) plus part_size: split the file into part_size-byte chunks and PUT chunk i to upload.urls[i] (the last may be smaller; small files come back as a single URL). Then finalize and poll until READY.

Request body

A discriminated union on kind, shared by the Publishing and Social APIs. The example shows an item audio upload. SOCIAL_POST_VIDEO uploads take only kind, content_type and num_bytes. Attach the result to a post as upload_id via Update Social Post.

kindMediaKindrequired

Kind of media to upload.

feed_idstringoptional

ID of the target feed. Not for SOCIAL_POST_VIDEO.

File MIME type.

num_bytesnumberrequired

File size in bytes. Max 10 MB for images, 400 MB for audio, 20 GB for item video, 16 GB for social video.

item_idstringoptional

ID of the target item. For ITEM_IMAGE, ITEM_AUDIO and ITEM_VIDEO.

access'DEFAULT' | 'PAID'optional

Item slot the upload can attach to. For ITEM_AUDIO and ITEM_VIDEO. Defaults to DEFAULT.

Responses

200The upload was started.

mediaMediarequired

The tracked upload (status PENDING).

uploadobjectrequired

The presigned multipart upload.

urlsstring[]required

Ordered presigned part URLs; PUT each chunk to its URL.

part_sizenumberrequired

The chunk size in bytes (except a possibly smaller last part).

Example request

curl -X POST "https://api.fountain.fm/v1/uploads" \
  -H "Authorization: Bearer $FOUNTAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"ITEM_AUDIO","feed_id":"a1b2c3d4","item_id":"e5f6g7h8","content_type":"audio/mpeg","num_bytes":48218112}'

Request body

{
  "kind": "ITEM_AUDIO",
  "feed_id": "a1b2c3d4",
  "item_id": "e5f6g7h8",
  "content_type": "audio/mpeg",
  "num_bytes": 48218112
}

Response · 200

{
  "ok": true,
  "media": {
    "id": "6f1a2b3c-4d5e-6f70-8901-23456789abcd",
    "kind": "ITEM_AUDIO",
    "status": "PENDING"
  },
  "upload": {
    "urls": [
      "https://r2.fountain.fm/uploads/6f1a2b3c/part-1?...",
      "https://r2.fountain.fm/uploads/6f1a2b3c/part-2?..."
    ],
    "part_size": 100000000
  }
}

Get Upload

GEThttps://api.fountain.fm/v1/uploads/{id}

Poll an upload until its status is READY, then attach its id as image_id, audio_default_id, audio_paid_id, video_default_id or video_paid_id. A failed upload reports ERROR. Transcription runs separately after READY and does not block attaching the media.

Path parameters

idstringrequired

The upload to poll.

Responses

200The upload.

mediaMediarequired

The upload.

Example request

curl -X GET "https://api.fountain.fm/v1/uploads/{id}" \
  -H "Authorization: Bearer $FOUNTAIN_API_KEY"

Response · 200

{
  "ok": true,
  "media": {
    "id": "6f1a2b3c-4d5e-6f70-8901-23456789abcd",
    "kind": "ITEM_AUDIO",
    "status": "READY",
    "preview_url": "https://media.fountain.fm/episodes/e5f6g7h8/audio.mp3"
  }
}

Finalize Upload

POSThttps://api.fountain.fm/v1/uploads/{id}/finalize

Call once every chunk has been PUT; processing then begins. Returns MEDIA_NOT_READY (409) if not every part has landed yet. Images and audio finish in seconds. Video is transcoded to HLS and can take minutes, so poll Get Upload until READY. A SOCIAL_POST_VIDEO upload needs no processing and is READY as soon as it is finalized.

Path parameters

idstringrequired

The upload to finalize.

Responses

200Processing has begun.

mediaMediarequired

The upload (status PROCESSING, or READY for a SOCIAL_POST_VIDEO).

Example request

curl -X POST "https://api.fountain.fm/v1/uploads/{id}/finalize" \
  -H "Authorization: Bearer $FOUNTAIN_API_KEY"

Response · 200

{
  "ok": true,
  "media": {
    "id": "6f1a2b3c-4d5e-6f70-8901-23456789abcd",
    "kind": "ITEM_AUDIO",
    "status": "PROCESSING"
  }
}