Browse Docs

Core

Endpoints

Converters

Options Reference

Archives (14)

Audio (38)

Documents (26)

Ebooks (7)

Fonts (13)

Images (62)

Video (10)

On This Page

Method + path
Auth
Content type
Form fields
Response
Example response (trimmed)
Examples
Audio transcription with options
With webhook notification
Errors

Endpoint: Convert

Method + path

POST /convert

Auth

Recommended: X-Fast-Api-Key

Content type

multipart/form-data required.

Form fields

file (required): single uploaded file
targetFormat (required): desired output format (jpg, png, pdf, etc.)
options (optional): JSON string for converter options
webhookUrl (optional): HTTPS URL to receive a webhook POST on job completion
webhookSecret (optional, required with webhookUrl): Shared secret for HMAC-SHA256 signature verification (16–256 characters)
webhookEvents (optional): Comma-separated event filter: succeeded, failed, or both (default: both)

Notes:

Exactly one file per request.
targetFormat can also be provided via query string as fallback: POST /convert?targetFormat=jpg
Some converters use compound targetFormat values that differ from simple format names — e.g. bank-statement-excel (not excel), pdf-ocr (not pdf). Use GET /convert/conversions to discover the exact targetFormat values.

Response

202 Accepted with JobAcceptedResponse

Example response (trimmed)

{
  "id": "019c56454f8b755996c45a4874a1f3f6",
  "status": "Queued",
  "creditCost": 1
}

Examples

# export API_KEY="your-api-key-here"
curl -sS -X POST "https://api.tools.fast/convert" \
  -H "X-Fast-Api-Key: $API_KEY" \
  -F "file=@photo.heic" \
  -F "targetFormat=jpg"

# with options JSON
curl -sS -X POST "https://api.tools.fast/convert" \
  -H "X-Fast-Api-Key: $API_KEY" \
  -F "file=@photo.jpg" \
  -F "targetFormat=webp" \
  -F 'options={"resize":{"enabled":true,"preset":"1080p"}}'

# $env:API_KEY = "your-api-key-here"
Invoke-RestMethod -Method Post "https://api.tools.fast/convert" `
  -Headers @{ "X-Fast-Api-Key" = $env:API_KEY } `
  -Form @{ file = Get-Item "photo.heic"; targetFormat = "jpg" }

# with options JSON
Invoke-RestMethod -Method Post "https://api.tools.fast/convert" `
  -Headers @{ "X-Fast-Api-Key" = $env:API_KEY } `
  -Form @{
    file = Get-Item "photo.jpg"
    targetFormat = "webp"
    options = '{"resize":{"enabled":true,"preset":"1080p"}}'
  }

Audio transcription with options

Transcription converters accept a transcription options object to control mode and output formats. See Options Reference for all settings.

# Transcribe audio to text (quality mode with SRT subtitles)
curl -sS -X POST "https://api.tools.fast/convert" \
  -H "X-Fast-Api-Key: $API_KEY" \
  -F "file=@meeting.mp3" \
  -F "targetFormat=txt" \
  -F 'options={"transcription":{"mode":"quality","includeSrt":true}}'

# Transcribe audio to text (quality mode with SRT subtitles)
Invoke-RestMethod -Method Post "https://api.tools.fast/convert" `
  -Headers @{ "X-Fast-Api-Key" = $env:API_KEY } `
  -Form @{
    file = Get-Item "meeting.mp3"
    targetFormat = "txt"
    options = '{"transcription":{"mode":"quality","includeSrt":true}}'
  }

With webhook notification

# Convert with webhook — no polling needed
curl -sS -X POST "https://api.tools.fast/convert" \
  -H "X-Fast-Api-Key: $API_KEY" \
  -F "file=@photo.heic" \
  -F "targetFormat=jpg" \
  -F "webhookUrl=https://example.com/webhooks/fast" \
  -F "webhookSecret=whsec_your_secret_here"

# Convert with webhook — no polling needed
Invoke-RestMethod -Method Post "https://api.tools.fast/convert" `
  -Headers @{ "X-Fast-Api-Key" = $env:API_KEY } `
  -Form @{
    file = Get-Item "photo.heic"
    targetFormat = "jpg"
    webhookUrl = "https://example.com/webhooks/fast"
    webhookSecret = "whsec_your_secret_here"
  }

See Webhooks for payload schema, signature verification, and retry policy.

Errors

See Errors for the full error reference with JSON examples.

Status	Codes	Cause
`400`	`request.invalid_content_type`, `request.no_files`, `request.empty_file`, `request.multiple_files`, `request.invalid_extension`, `convert.missing_target_format`, `convert.unsupported_format_pair`, `convert.unsupported_source_format`, `convert.invalid_options`	Bad request payload
`401`	`api_key.invalid_or_ip_not_allowed`	Invalid API key or IP not allowlisted
`402`	`entitlements.insufficient_credits`	Not enough credits
`413`	`request.file_too_large`	File exceeds size limit
`429`	`rate_limited`, `queue.limit_exceeded`	Throttled

Example — unsupported format pair:

{
  "error": "convert.unsupported_format_pair",
  "detail": "Conversion from 'jpg' to 'mp3' is not supported.",
  "sourceFormat": "jpg",
  "targetFormat": "mp3",
  "supportedTargets": ["avif", "ico", "pdf", "png", "webp"]
}

List Conversions

Jobs

# Endpoint: Convert

## Method + path

- `POST /convert`

## Auth

- Recommended: `X-Fast-Api-Key`

## Content type

- `multipart/form-data` required.

## Form fields

- `file` (required): single uploaded file
- `targetFormat` (required): desired output format (`jpg`, `png`, `pdf`, etc.)
- `options` (optional): JSON string for converter options
- `webhookUrl` (optional): HTTPS URL to receive a webhook POST on job completion
- `webhookSecret` (optional, required with `webhookUrl`): Shared secret for HMAC-SHA256 signature verification (16–256 characters)
- `webhookEvents` (optional): Comma-separated event filter: `succeeded`, `failed`, or both (default: both)

Notes:

- Exactly one file per request.
- `targetFormat` can also be provided via query string as fallback: `POST /convert?targetFormat=jpg`
- Some converters use **compound targetFormat values** that differ from simple format names — e.g. `bank-statement-excel` (not `excel`), `pdf-ocr` (not `pdf`). Use `GET /convert/conversions` to discover the exact `targetFormat` values.

## Response

`202 Accepted` with `JobAcceptedResponse`

### Example response (trimmed)

```json
{
  "id": "019c56454f8b755996c45a4874a1f3f6",
  "status": "Queued",
  "creditCost": 1
}
```

## Examples

### cURL
```bash
# export API_KEY="your-api-key-here"
curl -sS -X POST "https://api.tools.fast/convert" \
  -H "X-Fast-Api-Key: $API_KEY" \
  -F "file=@photo.heic" \
  -F "targetFormat=jpg"

# with options JSON
curl -sS -X POST "https://api.tools.fast/convert" \
  -H "X-Fast-Api-Key: $API_KEY" \
  -F "file=@photo.jpg" \
  -F "targetFormat=webp" \
  -F 'options={"resize":{"enabled":true,"preset":"1080p"}}'
```

### PowerShell
```powershell
# $env:API_KEY = "your-api-key-here"
Invoke-RestMethod -Method Post "https://api.tools.fast/convert" `
  -Headers @{ "X-Fast-Api-Key" = $env:API_KEY } `
  -Form @{ file = Get-Item "photo.heic"; targetFormat = "jpg" }

# with options JSON
Invoke-RestMethod -Method Post "https://api.tools.fast/convert" `
  -Headers @{ "X-Fast-Api-Key" = $env:API_KEY } `
  -Form @{
    file = Get-Item "photo.jpg"
    targetFormat = "webp"
    options = '{"resize":{"enabled":true,"preset":"1080p"}}'
  }
```

### Audio transcription with options

Transcription converters accept a `transcription` options object to control mode and output formats. See [Options Reference](../converters/options.md#transcription) for all settings.

### cURL
```bash
# Transcribe audio to text (quality mode with SRT subtitles)
curl -sS -X POST "https://api.tools.fast/convert" \
  -H "X-Fast-Api-Key: $API_KEY" \
  -F "file=@meeting.mp3" \
  -F "targetFormat=txt" \
  -F 'options={"transcription":{"mode":"quality","includeSrt":true}}'
```

### PowerShell
```powershell
# Transcribe audio to text (quality mode with SRT subtitles)
Invoke-RestMethod -Method Post "https://api.tools.fast/convert" `
  -Headers @{ "X-Fast-Api-Key" = $env:API_KEY } `
  -Form @{
    file = Get-Item "meeting.mp3"
    targetFormat = "txt"
    options = '{"transcription":{"mode":"quality","includeSrt":true}}'
  }
```

### With webhook notification

### cURL
```bash
# Convert with webhook — no polling needed
curl -sS -X POST "https://api.tools.fast/convert" \
  -H "X-Fast-Api-Key: $API_KEY" \
  -F "file=@photo.heic" \
  -F "targetFormat=jpg" \
  -F "webhookUrl=https://example.com/webhooks/fast" \
  -F "webhookSecret=whsec_your_secret_here"
```

### PowerShell
```powershell
# Convert with webhook — no polling needed
Invoke-RestMethod -Method Post "https://api.tools.fast/convert" `
  -Headers @{ "X-Fast-Api-Key" = $env:API_KEY } `
  -Form @{
    file = Get-Item "photo.heic"
    targetFormat = "jpg"
    webhookUrl = "https://example.com/webhooks/fast"
    webhookSecret = "whsec_your_secret_here"
  }
```

See [Webhooks](../webhooks.md) for payload schema, signature verification, and retry policy.

## Errors

See [Errors](../errors.md) for the full error reference with JSON examples.

| Status | Codes | Cause |
|--------|-------|-------|
| `400` | `request.invalid_content_type`, `request.no_files`, `request.empty_file`, `request.multiple_files`, `request.invalid_extension`, `convert.missing_target_format`, `convert.unsupported_format_pair`, `convert.unsupported_source_format`, `convert.invalid_options` | Bad request payload |
| `401` | `api_key.invalid_or_ip_not_allowed` | Invalid API key or IP not allowlisted |
| `402` | `entitlements.insufficient_credits` | Not enough credits |
| `413` | `request.file_too_large` | File exceeds size limit |
| `429` | `rate_limited`, `queue.limit_exceeded` | Throttled |

**Example** — unsupported format pair:

```json
{
  "error": "convert.unsupported_format_pair",
  "detail": "Conversion from 'jpg' to 'mp3' is not supported.",
  "sourceFormat": "jpg",
  "targetFormat": "mp3",
  "supportedTargets": ["avif", "ico", "pdf", "png", "webp"]
}
```

Copied.