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

# Quickstart

> Get started with Convertly. API conversion, Image CDN delivery, dashboard workflows, storage, and automation.

<div className="docs-page-banner">
  <img src="https://mintcdn.com/convertly-0a879af2/ycfWoHsCeNUy0PZs/public/docs/quickstart/docs-quickstart.png?fit=max&auto=format&n=ycfWoHsCeNUy0PZs&q=85&s=09cb34ca39e8c073ec103fc31f92ab8c" alt="Quickstart" width="1672" height="240" data-path="public/docs/quickstart/docs-quickstart.png" />
</div>

Convertly is a media platform for products that **ingest**, **process**, **deliver**, and **automate** files. Most teams start in one of four places: a direct API call, edge delivery through the Image CDN, the hosted dashboard, or a background job with webhooks.

<div className="convertly-callout">
  API keys are shown once when created. Store yours in a server environment variable, never in client-side browser code.
</div>

## Platform at a glance

| Layer        | What you get                                                                   | Dashboard                                                                                                                                   | Docs                                                                                                       |
| ------------ | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| **Deliver**  | On-the-fly image and video transforms at the edge, smart cropping, signed URLs | [Image CDN](https://convertly.sh/app/image-cdn) · [Transform Lab](https://convertly.sh/app/image-cdn?tab=lab)                               | [Image CDN](/docs/image-cdn)                                                                               |
| **Process**  | Convert, compress, thumbnails, trim, GIFs, background removal, inspection      | [Convert](https://convertly.sh/app/convert) · [Compress](https://convertly.sh/app/compress) · [Forma AI](https://convertly.sh/app/forma-ai) | [Media conversion](/docs/media-conversion) · [Media tools](/docs/media-tools) · [Forma AI](/docs/ai-tools) |
| **Ingest**   | Workspace storage, folders, imports, origin sources for the CDN                | [Assets](https://convertly.sh/app/files) · [Sources](https://convertly.sh/app/sources)                                                      | [Files & storage](/docs/files-and-storage) · [Transfer API](/docs/transfer-api)                            |
| **Automate** | Async batches, visual workflows, signed webhooks                               | [Workflows](https://convertly.sh/app/workflows) · [History](https://convertly.sh/app/history)                                               | [Async jobs](/docs/async-processing) · [Webhooks](/docs/webhooks)                                          |

Video streaming (adaptive HLS/DASH playback) lives under **Streams** in the dashboard. See [Video streaming](/docs/video-streaming).

## Create an API key

<Steps>
  <Step title="Open API keys in the dashboard" icon="key">
    Sign in to [convertly.sh/app](https://convertly.sh/app), open your **account menu** (top right), choose **Settings**, then scroll to **API keys**.

    Workspace owners and admins can create and revoke keys. Other members can use existing keys.

    ```txt theme={"system"}
    cvly_...
    ```
  </Step>

  <Step title="Store the key on your server" icon="terminal">
    ```bash theme={"system"}
    export CONVERTLY_API_KEY="<paste-your-key-here>"
    ```

    Send it on every API request:

    ```http theme={"system"}
    Authorization: Bearer $CONVERTLY_API_KEY
    ```

    `x-api-key` is also supported. See [Authentication](/authentication).
  </Step>
</Steps>

<Note>
  **Image CDN signing keys** are separate from API keys. Manage delivery namespaces and signing keys under **Image CDN → Delivery** in the dashboard.
</Note>

## Choose your first path

<Columns cols={2}>
  <Card title="Convert a file (API)" icon="file-gear" href="#convert-a-file-with-the-api">
    Best when you need a processed file back immediately in your backend.
  </Card>

  <Card title="Deliver through Image CDN" icon="images" href="#deliver-with-the-image-cdn">
    Best when images or video already live on your site or in storage and you want transform URLs.
  </Card>

  <Card title="Use the dashboard" icon="table-columns" href="#use-the-dashboard-without-code">
    Best for manual batches, Forma AI, and testing transforms before you wire an integration.
  </Card>

  <Card title="Queue background work" icon="list-check" href="#queue-a-background-job">
    Best for large batches that should finish after the upload request returns.
  </Card>
</Columns>

## Convert a file with the API

Send `multipart/form-data` to `POST /api/convert`. Convertly validates your plan limits, processes the file, and returns metadata plus a `downloadUrl`.

```bash theme={"system"}
curl -X POST "https://convertly.sh/api/convert" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -F "files=@./input.png" \
  -F "format=webp" \
  -F "compression=82" \
  -F "resize=original" \
  -F "autoOrient=true"
```

The response includes a `files` array. Each item has the output filename, MIME type, size savings, and `downloadUrl`.

| Option               | Behavior                                                                            |
| -------------------- | ----------------------------------------------------------------------------------- |
| `saveToStorage=true` | Also store the upload and output in your Convertly workspace                        |
| `format=svg`         | Raster-to-SVG tracing (color by default; add `mono=true` for black-and-transparent) |
| `POST /api/compress` | Same upload shape, optimized for compression instead of format conversion           |

<Card title="Media conversion reference" icon="file-gear" href="/docs/media-conversion">
  Supported formats, resize modes, archives, and production patterns.
</Card>

## Deliver with the Image CDN

The Image CDN transforms **images and video** at request time. responsive sizes, format negotiation (`format=auto`), poster frames, trimmed clips, and smart cropping. You do not pre-generate variant files.

```
https://cdn.convertly.sh/{namespace}/{fileIdOrSlug}?w=1200&format=auto&q=auto
https://cdn.convertly.sh/{namespace}/{videoId}?format=mp4&w=1280&so=0&du=30
https://cdn.convertly.sh/{namespace}/o/{originSlug}/products/hero.jpg?w=800&format=webp
```

<Steps>
  <Step title="Pick a delivery namespace" icon="key">
    Open **Image CDN → Delivery** and copy your default namespace, or create one for each site or product surface.
  </Step>

  <Step title="Connect a source" icon="database">
    Choose where Convertly fetches originals from:

    * **Origin source**. a deployed public HTTPS site, bucket, or CDN folder ([Sources](https://convertly.sh/app/sources))
    * **Convertly Storage**. upload files in [Assets](https://convertly.sh/app/files) and use the file UUID or CDN slug in URLs
  </Step>

  <Step title="Preview transforms" icon="flask">
    Use **Image CDN → Transform Lab** to preview posters, clips, and image transforms and copy a production-ready URL before you ship it.
  </Step>

  <Step title="Install the SDK (optional)" icon="box">
    ```bash theme={"system"}
    npm install @convertly-sh/image
    ```

    Drop in `<ConvertlyImage>` or a framework loader so your app builds CDN URLs automatically.
  </Step>
</Steps>

<Warning>
  Installing `@convertly-sh/image` only rewrites URLs. You still need an **origin source** or **stored file** before CDN URLs resolve. The SDK does not upload your repo or sync local folders.
</Warning>

<Card title="End-to-end CDN setup guide" icon="images" href="/guides/image-cdn-setup">
  Origin vs storage, framework wiring, and verification checklist.
</Card>

## Use the dashboard without code

You can run most of the platform from [convertly.sh/app](https://convertly.sh/app) before writing integration code:

| Area                   | What to do                                                                                   |
| ---------------------- | -------------------------------------------------------------------------------------------- |
| **Assets**             | Upload files, organize folders, share read-only links, import from cloud connections         |
| **Convert / Compress** | Run one-off batches with the same options as the API                                         |
| **Forma AI**           | Generate, edit, upscale, and restyle images in the studio                                    |
| **Image CDN**          | Manage delivery namespaces, origins, presets, custom domains, cache purge, and Transform Lab |
| **Streams**            | Upload source video and publish adaptive HLS playback                                        |
| **Workflows**          | Chain convert, compress, tools, and storage steps; test runs before going live               |
| **Integrations**       | Connect WordPress sites with scoped storage and CDN provisioning                             |
| **History**            | Review past jobs and workflow runs                                                           |

<Card title="Dashboard workflows" icon="diagram-project" href="/docs/workflows">
  Build repeatable pipelines without deploying your own workers.
</Card>

## Queue a background job

Use `POST /api/jobs` when files should upload once, process on Convertly workers, and be polled later.

```bash theme={"system"}
curl -X POST "https://convertly.sh/api/jobs" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -F "jobType=convert" \
  -F "saveToStorage=true" \
  -F "files=@./image-1.png" \
  -F "files=@./image-2.png" \
  -F 'formats=["webp","jpg"]'
```

Poll status:

```bash theme={"system"}
curl "https://convertly.sh/api/jobs/{jobId}" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY"
```

Add [webhooks](/docs/webhooks) when your app should react as soon as a job or workflow finishes.

## API endpoint map

| Need                                                  | Endpoint                                                                  |
| ----------------------------------------------------- | ------------------------------------------------------------------------- |
| Convert immediately                                   | `POST /api/convert`                                                       |
| Compress immediately                                  | `POST /api/compress`                                                      |
| Run a media tool (thumbnail, trim, GIF, watermark, …) | `POST /api/media/{tool}`                                                  |
| Forma AI transforms                                   | `POST /api/ai/transform`                                                  |
| Queue a batch                                         | `POST /api/jobs`                                                          |
| Check job status                                      | `GET /api/jobs/{id}`                                                      |
| Upload into storage                                   | `POST /api/files` or `POST /api/uploads` (+ `POST /api/uploads/complete`) |
| Browse files and folders                              | `GET /api/files` · `GET /api/folders`                                     |
| Import from URL, ZIP, or cloud                        | `POST /api/transfer`                                                      |
| Edge image/video transforms                           | `GET /cdn/v1/{namespace}/…`                                               |
| Manage CDN keys, origins, presets                     | `/api/delivery-keys` · `/api/cdn-origins` · `/api/cdn-presets`            |
| Adaptive video playback                               | `POST /api/video/streams` · `GET /video/v1/{playbackId}/…`                |

## Next steps

<Columns cols={3}>
  <Card title="Dashboard workflows" icon="table-columns" href="#use-the-dashboard-without-code">
    Use the hosted app for files, Image CDN tabs, Forma AI, and repeatable workflows.
  </Card>

  <Card title="Authentication & limits" icon="key" href="/authentication">
    Headers, WordPress site tokens, and plan quotas.
  </Card>

  <Card title="Plan limits" icon="gauge-high" href="/limits">
    Full quota tables for every plan tier.
  </Card>

  <Card title="SDKs" icon="code" href="/docs/sdk">
    `@convertly-sh/sdk`, `@convertly-sh/image`, and PHP client.
  </Card>

  <Card title="API reference" icon="code" href="/api-reference/media/convert-files">
    Interactive schemas and playground examples.
  </Card>

  <Card title="Use cases" icon="lightbulb" href="/docs/use-cases">
    SaaS uploads, marketplaces, ecommerce, and agency batches.
  </Card>

  <Card title="MCP for AI agents" icon="robot" href="/docs/mcp-agents">
    Let Cursor, Claude, and Codex work with approved local folders.
  </Card>

  <Card title="Image CDN setup" icon="images" href="/guides/image-cdn-setup">
    Wire origins, namespaces, and the SDK on your site.
  </Card>
</Columns>