> ## Documentation Index
> Fetch the complete documentation index at: https://docs.snipp.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# Convert a File

> Convert one image or video and get the converted bytes back. Nothing is stored.

Convert one image or video to another format and get the converted file back. Nothing is stored, no post is created, and no quota is used.

## Headers

| Header | Required | Description |
| - | - | - |
| `api-key` | Yes | Your API key, or a team access key |
| `convert-target` | Yes | `png`, `jpeg`, `webp`, `avif`, `gif`, `mp4` or `mp3` |

## Behavior

* Send the file as `multipart/form-data` in the `file` field. Only the first file is read.
* On success the body is the converted file itself, sent as an attachment, not JSON. Errors are JSON like every other endpoint.
* The source type is detected from the file's bytes, not its name.
* **What converts to what:** PNG, JPG and WebP convert to `png`, `jpeg`, `webp`, `avif` or `gif`. GIF converts to `png`, `jpeg`, `webp`, `avif` or `mp4`. MP4, MOV and MKV convert to `mp4`, `gif` or `mp3`.
* **Video to GIF requires Plus.** It uses the first 10 seconds at 15 fps and 480 px wide.
* **MP4 output** is remuxed with `+faststart` when the source is already H.264, and transcoded otherwise.
* **Metadata is always stripped.** JPG orientation is applied to the pixels first, so photos stay upright.
* Files are capped at 50 MB on Free, 20 GB on Plus, and 50 GB on Ultra and team keys. Converting does not count toward your weekly quota.
* Conversion runs inside the request, so a large video can take a while.
* To host the result, upload it with [`POST /upload`](/api-reference/endpoint/upload). AVIF and MP3 are not upload types, so those are download-only.
* Rate limited to 10 conversions per minute.

## Examples

```bash theme={null}
curl -X POST "https://api.snipp.gg/convert" \
  -H "api-key: YOUR_API_KEY" \
  -H "convert-target: webp" \
  -F "file=@screenshot.png" \
  -o screenshot.webp
```

```bash theme={null}
curl -X POST "https://api.snipp.gg/convert" \
  -H "api-key: YOUR_API_KEY" \
  -H "convert-target: mp3" \
  -F "file=@clip.mp4" \
  -o clip.mp3
```

## Responses

On success the headers name the file:

```
HTTP/1.1 200 OK
Content-Type: image/webp
Content-Disposition: attachment; filename="screenshot.webp"
Content-Length: 184320
```

On failure the body is JSON:

```json theme={null}
{
  "error": {
    "type": "unsupported_type",
    "message": "That file cannot be converted to this format."
  }
}
```

## Errors

| Status | Type | When |
| - | - | - |
| `400` | `invalid_request` | Missing or invalid `convert-target`, or no file |
| `400` | `unsupported_type` | The source type is not supported, or cannot become the target |
| `401` | `unauthorized` | Missing or invalid key |
| `403` | `plan_required` | Video to GIF without Plus |
| `403` | `forbidden` | The team's subscription has lapsed |
| `413` | `file_too_large` | The file is over your limit |
| `429` | `rate_limited` | More than 10 conversions per minute |
| `500` | `internal` | The conversion failed |


## OpenAPI

````yaml api-reference/openapi.json POST /convert
openapi: 3.0.0
info:
  title: Snipp.gg API
  description: Image and video hosting API. Upload, manage, and share media files.
  version: 3.0.0
servers:
  - url: https://api.snipp.gg
    description: Default. Load-balanced across regions. No upload cap.
  - url: https://eu-west-1.api.snipp.gg
    description: EU West regional endpoint. Pins uploads and storage to EU West.
  - url: https://us-west-1.api.snipp.gg
    description: US West regional endpoint. Pins uploads and storage to US West.
  - url: https://flux.snipp.gg
    description: Alternative host. Capped at 100 MB per upload.
security:
  - apiKeyAuth: []
paths:
  /convert:
    post:
      summary: Convert a File
      description: >-
        Convert one image or video and get the converted bytes back. Nothing is
        stored.
      operationId: convert
      parameters:
        - name: convert-target
          in: header
          required: true
          description: Output format.
          schema:
            type: string
            enum:
              - png
              - jpeg
              - webp
              - avif
              - gif
              - mp4
              - mp3
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: The file to convert.
              required:
                - file
      responses:
        '200':
          description: The converted file, sent as an attachment.
          headers:
            request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/E400'
        '401':
          $ref: '#/components/responses/E401'
        '403':
          $ref: '#/components/responses/E403'
        '405':
          $ref: '#/components/responses/E405'
        '413':
          $ref: '#/components/responses/E413'
        '429':
          $ref: '#/components/responses/E429'
        '500':
          $ref: '#/components/responses/E500'
components:
  headers:
    RequestId:
      description: Unique ID for the request. Include it when contacting support.
      schema:
        type: string
        format: uuid
  responses:
    E400:
      description: Invalid request
      headers:
        request-id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    E401:
      description: Missing or invalid key
      headers:
        request-id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    E403:
      description: Not allowed
      headers:
        request-id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    E405:
      description: Method not allowed
      headers:
        request-id:
          $ref: '#/components/headers/RequestId'
        Allow:
          description: Methods this path accepts.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    E413:
      description: File too large
      headers:
        request-id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    E429:
      description: Rate limited
      headers:
        request-id:
          $ref: '#/components/headers/RequestId'
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    E500:
      description: Internal error
      headers:
        request-id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
      required:
        - error
      description: Every non-2xx response has this body.
    ErrorDetail:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ErrorType'
        message:
          type: string
          description: Human-readable sentence. Do not match on it; use `type`.
        username:
          type: string
          description: >-
            `suspended` on `GET /users/{id}` only: the suspended user's
            username.
        quota:
          type: integer
          description: '`quota_exceeded` only: weekly quota in bytes.'
        used:
          type: integer
          description: '`quota_exceeded` only: bytes used in the current window.'
        resets_at:
          type: string
          format: date-time
          description: '`quota_exceeded` only: when the weekly window resets.'
          nullable: true
        failed:
          type: array
          items:
            $ref: '#/components/schemas/FailedFile'
          description: '`upload_failed` only: one entry per file.'
      required:
        - type
        - message
    ErrorType:
      type: string
      enum:
        - invalid_request
        - unauthorized
        - forbidden
        - suspended
        - blocked
        - moderated
        - plan_required
        - not_found
        - method_not_allowed
        - file_too_large
        - unsupported_type
        - quota_exceeded
        - rate_limited
        - upload_failed
        - internal
        - unavailable
      description: Machine-readable error category. See [Errors](/concepts/errors).
    FailedFile:
      type: object
      properties:
        index:
          type: integer
          description: Zero-based position of the file in the request.
        error:
          $ref: '#/components/schemas/ErrorDetail'
      required:
        - index
        - error
      description: >-
        A file that was not stored. `error` has the same shape as a top-level
        error.
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: api-key
      description: Your API key from the Snipp Console

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.