Media Upload

Learn how to prepare and upload media files from various sources including direct URLs, Google Drive, Dropbox, and AWS S3.

Media Preparation Workflow

SocialHub uses a two-step process for handling media files:

Prepare: Submit media URLs to the preparation endpoint
Check Status: Poll the status endpoint until preparation is complete
Publish: Use the prepared media URLs in your publication request

Step 1: Prepare Media Files

Submit your media URLs to the preparation endpoint. SocialHub will download, validate, and optimize the files:

Prepare Media Filesbash

curl -X POST https://your-domain.com/api/agents/v1/media/prepare \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://example.com/image1.jpg",
      "https://drive.google.com/file/d/ABC123/view",
      "https://www.dropbox.com/s/xyz789/video.mp4"
    ]
  }'

Response:

{
  "success": true,
  "task_id": "task_abc123",
  "message": "Media preparation started"
}

Step 2: Check Preparation Status

Use the task_id to check the preparation status. Poll this endpoint every few seconds until the status is completed:

Check Media Statusbash

curl -X GET "https://your-domain.com/api/agents/v1/media/status/task_abc123" \
  -H "X-API-Key: your_api_key_here"

Response when processing:

{
  "status": "processing",
  "progress": {
    "total": 3,
    "completed": 1,
    "failed": 0
  }
}

Response when completed:

{
  "status": "completed",
  "files": [
    {
      "original_url": "https://example.com/image1.jpg",
      "prepared_url": "https://your-s3.amazonaws.com/uploads/image1.jpg",
      "type": "image",
      "size": 2048576
    },
    {
      "original_url": "https://drive.google.com/file/d/ABC123/view",
      "prepared_url": "https://your-s3.amazonaws.com/uploads/image2.jpg",
      "type": "image",
      "size": 1572864
    }
  ]
}

Step 3: Use Prepared Media in Publication

Once preparation is complete, use the prepared_url values in your publication request:

Publish with Prepared Mediabash

curl -X POST https://your-domain.com/api/agents/v1/content/publish \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "Check out these photos! 📸",
    "platforms": ["instagram"],
    "media_urls": [
      "https://your-s3.amazonaws.com/uploads/image1.jpg",
      "https://your-s3.amazonaws.com/uploads/image2.jpg"
    ],
    "publish_now": true
  }'

Supported Media Sources

Direct HTTP/HTTPS URLs

Any publicly accessible URL

https://example.com/image.jpg

Google Drive

Shared Google Drive file links

https://drive.google.com/file/d/...

Dropbox

Shared Dropbox file links

https://www.dropbox.com/s/...

AWS S3

Public S3 bucket URLs

https://bucket.s3.region.amazonaws.com/...

Limitations and Constraints

Max File Size:500 MB per file
Max Files:10 files per preparation request
Timeout:10 minutes for preparation
Supported Formats:JPEG, PNG, GIF, MP4, MOV, AVI

Important

Prepared media files are temporary and will be deleted 24 hours after preparation. Use them in your publications promptly after preparation completes.

Complete Example: TypeScript

import axios from 'axios';

const API_KEY = process.env.SOCIALHUB_API_KEY;
const BASE_URL = 'https://your-domain.com/api/agents/v1';

async function publishWithMedia() {
  // Step 1: Prepare media
  const prepareResponse = await axios.post(
    `${BASE_URL}/media/prepare`,
    {
      urls: [
        'https://example.com/image1.jpg',
        'https://example.com/image2.jpg'
      ]
    },
    {
      headers: {
        'X-API-Key': API_KEY,
        'Content-Type': 'application/json'
      }
    }
  );

  const taskId = prepareResponse.data.task_id;
  console.log('Preparation started:', taskId);

  // Step 2: Poll for completion
  let status = 'processing';
  let preparedUrls: string[] = [];

  while (status === 'processing') {
    await new Promise(resolve => setTimeout(resolve, 3000)); // Wait 3 seconds

    const statusResponse = await axios.get(
      `${BASE_URL}/media/status/${taskId}`,
      {
        headers: { 'X-API-Key': API_KEY }
      }
    );

    status = statusResponse.data.status;

    if (status === 'completed') {
      preparedUrls = statusResponse.data.files.map(
        (file: any) => file.prepared_url
      );
      console.log('Preparation completed:', preparedUrls);
    }
  }

  // Step 3: Publish with prepared media
  const publishResponse = await axios.post(
    `${BASE_URL}/content/publish`,
    {
      caption: 'Check out these photos! 📸',
      platforms: ['instagram'],
      media_urls: preparedUrls,
      publish_now: true
    },
    {
      headers: {
        'X-API-Key': API_KEY,
        'Content-Type': 'application/json'
      }
    }
  );

  console.log('Published:', publishResponse.data);
}

publishWithMedia();

Next: Advanced Examples

Explore complex automation scenarios and integration patterns in theAdvanced Examples section.