About uploaded media
What is an uploaded media?
media_url field.Recommended upload flow
1.
POST /api/v1/medias/direct_uploads to get a direct upload URL, headers, and a signed_id.2.
direct_upload.url, including the returned direct_upload.headers. This upload goes directly to Peach storage, not back to the Peach API.3.
POST /api/v1/medias/finalize with the signed_id to attach the blob into Peach's media library.4.
media_url (media://...) in subsequent API calls.Example requests
1. Create a direct upload
{
"id": 101,
"key": "1/abc123def456",
"filename": "sample.png",
"content_type": "image/png",
"metadata": {
"source": "api",
"peach_media_direct_upload": true,
"account_id": 1
},
"byte_size": 128349,
"checksum": "I+Sf6zGPGY+9Fh0ymkvwow==",
"created_at": "2026-04-22T10:00:00.000Z",
"signed_id": "eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBdz09IiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--example",
"direct_upload": {
"url": "https://storage.example.com/upload",
"headers": {
"Content-Type": "image/png"
}
}
}2. Upload the bytes to storage
direct_upload.url and direct_upload.headers from the previous response.direct_upload.headers contains additional headers, include them exactly as returned.3. Finalize the upload
{
"id": 55,
"filename": "sample.png",
"content_type": "image/png",
"signed_id": "eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBdz09IiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--example",
"media_url": "media://101",
"created_at": "2026-04-22T10:00:05.000Z"
}Common error responses
401 Unauthorized
{
"message": "Unauthorized"
}413 Payload Too Large
{
"status": "failed",
"reason": {
"blob": {
"byte_size": [
"is too large (max 5242880 bytes for image/png)"
]
}
}
}422 Unprocessable Entity
{
"status": "failed",
"reason": {
"blob": {
"content_type": [
"is not supported. Supported values: image/jpeg, image/png, video/mp4, video/3gpp, application/pdf, text/plain, application/vnd.ms-excel, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/vnd.ms-powerpoint, application/vnd.openxmlformats-officedocument.presentationml.presentation, audio/mp4, audio/mpeg, audio/amr, audio/ogg, audio/aac"
]
}
}
}{
"status": "failed",
"reason": {
"blob": {
"content_type": [
"is blank"
]
}
}
}Legacy upload endpoint
POST /api/v1/medias still works for backward compatibility, but it is deprecated and should not be used for new integrations. It uploads base64 data through the app servers and is less performant.{
"id": 55,
"filename": "sample.png",
"content_type": "image/png",
"signed_id": "eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBdz09IiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--example",
"media_url": "media://101",
"created_at": "2026-04-22T10:00:05.000Z"
}Orphaned uploads
Why use uploaded media over inline file URLs?
Notes
content_type is required for direct uploads..jpeg file should use image/jpeg.Modified at 2026-04-22 04:48:05