Skip to main content

​
Media API

The Media API lets you upload remote media files to the Soku media library. Once uploaded, the returned URL can be used in post submissions for video and image content.

​
Upload Remote Media

Download a media file from a remote URL and store it in the Soku media library. 
POST /v1/media

​
Headers

HeaderRequiredDescription
Content-TypeYesMust be application/json
soku-api-keyYesYour Soku API key
Idempotency-KeyNoA unique string to prevent duplicate uploads. If omitted, Soku auto-derives a key from your user ID and request payload.

​
Request Body

FieldTypeRequiredDescription
urlstringYesThe publicly accessible URL of the media file to upload. Must be a valid HTTP or HTTPS URL.

​
Response

FieldTypeDescription
urlstringThe Soku-hosted URL of the uploaded media file. Use this URL in the mediaUrls, videoUrl, or imageUrls fields when creating posts.
{
  "url": "https://storage.mysoku.io/media/a1b2c3d4/uploaded-file.mp4"
}

​
Examples

​
Upload a video from a remote URL

curl -X POST https://api.mysoku.io/v1/media \
  -H "Content-Type: application/json" \
  -H "soku-api-key: sk_live_your_api_key_here" \
  -d '{
    "url": "https://example.com/videos/product-demo.mp4"
  }'
Response: 
{
  "url": "https://storage.mysoku.io/media/f7e8d9c0/product-demo.mp4"
}

​
Upload an image

curl -X POST https://api.mysoku.io/v1/media \
  -H "Content-Type: application/json" \
  -H "soku-api-key: sk_live_your_api_key_here" \
  -d '{
    "url": "https://example.com/images/banner.png"
  }'
Response: 
{
  "url": "https://storage.mysoku.io/media/b3c4d5e6/banner.png"
}

​
Upload and then publish

A common workflow is to upload media first, then use the returned URL in a post: 
# Step 1: Upload the media
MEDIA_URL=$(curl -s -X POST https://api.mysoku.io/v1/media \
  -H "Content-Type: application/json" \
  -H "soku-api-key: sk_live_your_api_key_here" \
  -d '{"url": "https://example.com/videos/demo.mp4"}' \
  | jq -r '.url')

# Step 2: Create a post using the uploaded media
curl -X POST https://api.mysoku.io/v1/posts \
  -H "Content-Type: application/json" \
  -H "soku-api-key: sk_live_your_api_key_here" \
  -d "{
    \"post\": {
      \"content\": {
        \"text\": \"Check out our latest demo\",
        \"mediaType\": \"video\",
        \"videoUrl\": \"$MEDIA_URL\",
        \"platform\": [\"instagram\", \"tiktok\", \"youtube\"]
      }
    }
  }"

​
Supported Media Formats

The Media API accepts any media file that the source URL serves over HTTP or HTTPS. For best results with social platform publishing, use the following formats:
TypeRecommended FormatsNotes
VideoMP4 (H.264)Most universally supported across all platforms
ImageJPEG, PNG, WebPJPEG recommended for photos, PNG for graphics
For detailed information on media format requirements and file size limits per platform, see Media Formats & Limits.

​
Error Responses

HTTP StatusError CodeDescription
400validation_errorThe url field is missing or not a valid URL
401unauthorizedMissing or invalid API key
403forbiddenSubscription is not active
429rate_limit_exceededToo many requests. See Rate Limits.
500internal_errorFailed to download or store the media file
Example error response: 
{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_error",
    "message": "The 'url' field must be a valid HTTP or HTTPS URL.",
    "timestamp": "2026-02-28T12:00:00.000Z",
    "requestId": "req_abc123def456"
  }
}

​
Next Steps

TopicDescription
Posts APIUse uploaded media in post submissions
Templates APIGenerate OG images programmatically
Media Formats & LimitsPlatform-specific media requirements