# Process images with the API from the terminal (curl)
> Hands-on guide to the SocialCutter API with curl: health, credentials, platforms, processing by URL and by file, history, wallet and common errors.
- URL: https://socialcutter.theboomer.dev/en/guides/curl/
- Idioma: en
- Familia: api
- Actualizado: 2026-09-24
- Palabras clave: curl, API, SocialCutter, terminal, jq, process images, API key
## Before you start

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

```bash
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

```bash
# 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

```bash
# 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

```bash
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

```bash
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.

```bash
# 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

```bash
# 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. |

```bash
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](/en/guides/mcp/)
- API reference: https://docs.socialcutter.theboomer.dev
- Dashboard: https://dash.socialcutter.theboomer.dev