Docs/Uploads

Uploads

Upload media for feeds, items and social posts.

Start Upload

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

With num_bytes, split the file into part_size-byte chunks and PUT chunk i to upload.urls[i]. The last chunk may be smaller; small files use one URL. Then finalize and poll until READY. With a public url, Fountain downloads the file itself: skip the chunks and finalize, and poll until READY.

Request body

Fields depend on kind. Each upload sets either num_bytes or url. SOCIAL_POST_VIDEO requires only kind, content_type and one of the two. Attach it as upload_id with Update Social Post. An ITEM_VIDEO HLS stream (application/x-mpegURL) needs url.

kindMediaKindrequired

Kind of media to upload.

feed_idstringoptional

ID of the target feed. Not for SOCIAL_POST_VIDEO.

File MIME type.

num_bytesnumberoptional

File size in bytes, for uploading the file in parts. Max 10 MB for images, 400 MB for audio, 20 GB for item video, 16 GB for social video. Set this or url.

urlstringoptional

Public URL of the file, as an alternative to uploading the file in parts. Fountain downloads it, and no finalize call is needed. Set this or num_bytes.

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

200Upload started.

mediaMediarequired

Upload with status PENDING.

uploadobjectoptional

The presigned multipart upload. Absent when the upload has a url.

urlsstring[]required

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

part_sizenumberrequired

Chunk size in bytes. The last chunk may be smaller.

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 until READY, then attach the upload ID as image_id, audio_default_id, audio_paid_id, video_default_id or video_paid_id. Failed uploads return ERROR. Transcription runs separately and does not block media attachment.

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

Start processing after all chunks are uploaded. Missing parts return 409 MEDIA_NOT_READY. Images and audio process in seconds; video transcodes to HLS and can take minutes. Poll Get Upload until READY. SOCIAL_POST_VIDEO uploads are ready immediately. An upload created with a url needs no finalize.

Path parameters

idstringrequired

The upload to finalize.

Responses

200Upload finalized.

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"
  }
}