Process images with the API from the terminal (curl)

Before you start

You need curl and jq. Store the base URL and the key in variables so you do not repeat them:

export API_URL="https://api.socialcutter.theboomer.dev"
export API_KEY="sc_your_key"

The full reference lives at https://docs.socialcutter.theboomer.dev.

1. Get the API key

Open https://dash.socialcutter.theboomer.dev, go to Profile → API keys and create a key. It starts with sc_, is shown only once, and only one key can be active per account. If you create another without revoking the first, the API returns 400.

2. Check health and credentials

# Health: public endpoint, no key needed
curl -s "$API_URL/api/v1/health" | jq

# Identity of the account using the key
curl -s "$API_URL/api/v1/auth/me" -H "X-API-Key: $API_KEY" | jq

# Available uses
curl -s "$API_URL/api/v1/credits" -H "X-API-Key: $API_KEY" | jq

/api/v1/health returns the service status, version, uptime and database connectivity. /api/v1/auth/me confirms which account the key belongs to. If that call returns 401, the key is wrong or revoked.

3. List platforms, formats and fit modes

# Response shape: top-level keys first
curl -s "$API_URL/api/v1/platforms" | jq 'keys'

# Every platform with its formats, sizes and aspect ratio
curl -s "$API_URL/api/v1/platforms" | jq

# Output formats and fit modes
curl -s "$API_URL/api/v1/formats" | jq
curl -s "$API_URL/api/v1/fit-modes" | jq

/platforms, /formats and /fit-modes are public. Start with jq 'keys' to see the real response shape, then drill into it with the path you need.

These are the combinations destinations accepts:

Platform	Format	Size	Aspect ratio
instagram	post	1080x1080	1:1
instagram	story	1080x1920	9:16
instagram	landscape	1080x566	1.91:1
facebook	post	1200x630	1.91:1
facebook	story	1080x1920	9:16
facebook	cover	820x312	2.63:1
twitter	post	1200x675	16:9
twitter	header	1500x500	3:1
linkedin	post	1200x627	1.91:1
linkedin	cover	1128x191	5.9:1
youtube	thumbnail	1280x720	16:9
youtube	banner	2560x1440	16:9
tiktok	cover	1080x1920	9:16

4. Process an image by URL

curl -s -X POST "$API_URL/api/v1/images/process" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-001" \
  -d '{
    "source": { "type": "url", "value": "https://example.com/photo.jpg" },
    "destinations": [
      { "platform": "instagram", "format": "post" },
      { "platform": "tiktok", "format": "cover" }
    ]
  }' | jq

source says where the image comes from (url or base64) and destinations is the list of platform and format you want. The Idempotency-Key header makes retries safe; without it the API generates a random key per request.

5. Process a local file

curl -s -X POST "$API_URL/api/v1/images/process/upload" \
  -H "X-API-Key: $API_KEY" \
  -F "file=@./photo.jpg" \
  -F 'destinations=[{"platform":"linkedin","format":"post"},{"platform":"youtube","format":"thumbnail"}]' | jq

In multipart the file goes in file and destinations is a JSON string in a form field. The limit is 5 MB; above that the API returns 413.

Base64 alternative

POST /api/v1/images/upload takes the image as a base64 string in the JSON body, with no file and no source URL. Use it only when the image has no reachable public URL.

6. Read the response and download a result

The response carries image_id and an outputs list, one entry per destination, with the result URL, the platform, the format and the dimensions.

# Save the response to a file
curl -s -X POST "$API_URL/api/v1/images/process" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": { "type": "url", "value": "https://example.com/photo.jpg" },
    "destinations": [{ "platform": "instagram", "format": "post" }]
  }' > out.json

# Id, platform and format of each output
jq '.image_id, (.outputs[] | {url, platform, format})' out.json

# Download the first result
curl -s -o result.webp "$(jq -r '.outputs[0].url' out.json)"

If a dimension key is missing, print the whole object with jq '.outputs[0]' to see its real shape.

7. History and wallet

# Last 10 images
curl -s "$API_URL/api/v1/history?limit=10" -H "X-API-Key: $API_KEY" | jq

# Only the ones created from the API
curl -s "$API_URL/api/v1/history?origin=api&limit=10" -H "X-API-Key: $API_KEY" | jq

# Wallet: daily quota, used, remaining, bonus bag and purchased balance
curl -s "$API_URL/api/v1/wallet" -H "X-API-Key: $API_KEY" | jq

limit accepts 1 to 100 (default 50) and skip paginates. The origin filter separates browser (dashboard) from api.

8. Choose the fit mode

fit_mode controls how the image fits each format:

Mode	Behaviour
cover	Scales and crops the excess with a centered crop. This is the default.
contain	Fits the whole image and pads with background_color.
fill	Stretches the image.
stretch	Forces the exact dimensions.

curl -s -X POST "$API_URL/api/v1/images/process" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": { "type": "url", "value": "https://example.com/photo.jpg" },
    "destinations": [{ "platform": "facebook", "format": "cover" }],
    "options": { "fit_mode": "contain", "format": "webp", "quality": 85 }
  }' | jq

The cover crop is centered. In options you can also set format (webp, png, jpg, gif) and quality (1 to 100, default 85).

Retries, batches and pagination

• Reuse the same Idempotency-Key header when you retry a request: the API will not process it twice.
• POST /api/v1/images/batch processes several images in one call and reports the result per index. Failed items are refunded.
• GET /api/v1/history paginates with limit (1 to 100) and skip.
• Every response carries the X-Tentpole-Version header with the running build version.

Cost

• 1 use per destination (platform and format) per request.
• Duplicate destinations in the same request are not charged twice.
• Failed processing is refunded.

Common errors

Code	Meaning
400	Invalid payload: unknown platform, format or fit mode, malformed JSON, or a key already active
401	Missing, malformed, expired or revoked credentials
404	Resource not found (image or file id)
413	The file is over 5 MB
422	Request validation error
429	Wallet quota exhausted
500	Processing failure; the uses for that request are refunded

Next steps

• MCP guide: Use SocialCutter from your LLM or editor with MCP
• API reference: https://docs.socialcutter.theboomer.dev
• Dashboard: https://dash.socialcutter.theboomer.dev