ACME API Documentation logo

Upload Image or Video

Upload an image or small video file to include in your post

POSThttps://api.acme.com/api/media/upload
Available on Premium, Business, Enterprise plans.

This endpoint allows you to upload a file or an image or small video to include in your post. Returned will be the URL to the image that can be used in the /post endpoint.

You can pass the file either as a multipart form data as a form parameter or a Base64 encoded file as a body parameter.

Important notes about media uploads:

  1. For best performance, we recommend

    • Hosting media files on your own server (e.g. AWS S3).
    • Passing the media URL directly in the mediaUrls parameter of the /post endpoint.
    • This approach is faster than uploading files through this endpoint.

  2. Media file retention

    • Uploaded files are stored for 90 days.
    • After 90 days:
      • Published posts on social networks are unaffected.
      • Scheduled posts will fail to publish if they reference expired media.

  3. File size limits

If you already have your media accessible by an external URL, such as an S3 bucket, you can skip uploading the files to ACME. Just POST to the /post endpoint with your externally accessible URL in the mediaURLs body parameter and your file will automatically be uploaded.

Header Parameters

Authorizationstringrequired
API Key of the Primary Profile.

Format: Authorization: Bearer API_KEY
Content-Typestringrequired

Use multipart/form-data if sending a multipart form data - see below. Otherwise, send the standard application/json.

Body Parameters

filestring or objectrequired

Max 30 MB file size.

We recommend sending as a multipart form-data object instead of Base64 encoding.

fileNamestring

The name of the file to be uploaded.

descriptionstring

A description of the file.

Send as Multipart Form-Data

Send the media file as a multipart form-data object. Please be sure to specify the Content-Type as mentioned above.

Send as Base64

Send the media file as a Base64 encoded string as a Data URI string. The string should begin with data:content/type;base64

Example encoding with Output Format Data URI:

Note: The /post endpoint accepts larger files via an external URL with the mediaUrls parameter.

# Send as Multipart Form-Data
curl \
-H "Authorization: Bearer API_KEY" \
-F "file=@test.png" \
-F "fileName=test.png" \
-F "description=best image" \
-X POST https://api.acme.com/api/media/upload

# Send as Base64
curl \
-H "Authorization: Bearer API_KEY" \
-H 'Content-Type: application/json' \
-d '{"file": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...", "fileName": "test.png", "description": "best image"}' \
-X POST https://api.acme.com/api/media/upload
{
    "id": "1167335b-6c37-4fc6-ab8a-044e0005d335-jpeg",
    "url": "https://images.acme.com/q3Ls85VTsrbODnGIJHpy7PaHWwA3/1167335b-6c37-4fc6-ab8a-044ed885d.jpeg",
    "fileName": "fun.jpg",
    "description": "good times"
}