# Media requests

Resolve an intent or submit a download with explicit output and byte limits.

## Resolve an intent

`POST /media/resolve`

Body:

```json
{
    "url": "https://example.com/video.mp4"
}
```

Returns `200` with `status: "unverified"`, a detected `source.platform`, and generic variant choices. `title`, `thumbnail`, `duration`, and media URLs can be null. This endpoint does not download or probe the source. Availability is checked when the worker executes a download.

## Submit a download

`POST /media/download`

Authentication: partner API key or user session. Anonymous downloads depend on the deployment. Partner integrations should always send their key.

```json
{
    "url": "https://example.com/video.mp4",
    "delivery": "private",
    "output": {
        "type": "auto",
        "format": "original",
        "quality": "best"
    },
    "processing": {
        "fitToLimit": false
    }
}
```

| Field                     | Type             | Required | Meaning                                                                                |
| ------------------------- | ---------------- | -------- | -------------------------------------------------------------------------------------- |
| `url`                     | string           | Yes      | HTTP(S) media/page URL, at most 4096 characters; embedded credentials are not accepted |
| `delivery`                | string           | No       | `private` (default) or `public`                                                        |
| `output.type`             | string           | No       | `auto` (default), `video`, `audio`, `image`, `thumbnail`                               |
| `output.format`           | string           | No       | `original` (default), `mp4`, `mp3`, `jpg`                                              |
| `output.quality`          | string           | No       | `best` (default), `1080p`, `720p`, `480p`, `360p`, `audio-only`                        |
| `processing.fitToLimit`   | boolean          | No       | Whether to fit converted output to an allowed byte limit; default false                |
| `limits.maxBytes`         | positive integer | No       | Requested output ceiling when fitting                                                  |
| `limits.maxDownloadBytes` | positive integer | No       | Requested source-download ceiling                                                      |

Byte values are bytes, not megabytes. Account and operator ceilings still apply. Quality heights are preferences when source variants exist, not guaranteed dimensions. `audio-only` requires `original` or `mp3` format.

For source-preserving output, use `format: "original"` with `fitToLimit: false`. Explicit conversion or fitting can change the selected source. This does not recover quality missing from the source.

## Accepted response

Returns `202`, a `Location` header pointing to `/api/v1/jobs/:id`, and `Retry-After: 2`. The JSON contains `job.id`, `status`, `phase`, timestamps, `error`, and `result`.

Follow [job status](/docs/en/reference/jobs), then retrieve [files](/docs/en/reference/files). A worker failure is reported on the job, even though submission returned `202`.

## Duplicate submission protection

Optionally send `Idempotency-Key`. It must contain 8 to 200 printable non-space ASCII characters. Keys are scoped to the account.

An identical logical download with the same key returns the existing job. Reusing the key with different intent returns `409 IDEMPOTENCY_CONFLICT`. Keep the key after a submission timeout. A deliberate retry of a terminal failed job needs a new key.

## Audio and thumbnails

Audio example:

```json
{
    "url": "https://example.com/video.mp4",
    "output": {
        "type": "audio",
        "format": "mp3",
        "quality": "audio-only"
    }
}
```

Thumbnail example:

```json
{
    "url": "https://example.com/video.mp4",
    "output": {
        "type": "thumbnail",
        "format": "jpg",
        "quality": "best"
    }
}
```

Source support and extraction still apply. The API does not accept source-platform cookies from callers.

## Request examples

Choose a language. JavaScript and Node.js examples use a server environment, not a public browser key. Replace illustrative IDs with your own.

### Download a file

```request
{
    "method": "POST",
    "path": "/media/download",
    "body": {
        "url": "https://example.com/video.mp4",
        "output": {
            "type": "auto",
            "format": "original",
            "quality": "best"
        }
    }
}
```