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

# Media

> Upload, search, and manage images, audio, and video for your quizzes.

## Overview

Many question types reference media files -- images, audio clips, and videos. You can upload your own files or search external sources (Pexels, Freesound, Wikipedia). Uploaded media is stored in your personal library and can be reused across quizzes.

## Upload a File

Upload a file directly using `multipart/form-data`:

```bash theme={null}
curl -X POST https://app.quiz-quail.com/api/v1/media \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@./eiffel-tower.jpg"
```

```json theme={null}
{
  "id": "media-001",
  "file_name": "eiffel-tower.jpg",
  "mime_type": "image/jpeg",
  "size_bytes": 245832,
  "url": "https://storage.quizquail.com/media/user-123/1742083260-a1b2c3.jpg",
  "created_at": "2026-03-15T12:00:00Z"
}
```

### File Limits

| Type   | Max Size | Allowed Formats           |
| ------ | -------- | ------------------------- |
| Images | 10 MB    | JPEG, PNG, GIF, WebP, SVG |
| Audio  | 10 MB    | MP3, WAV, OGG, M4A        |
| Video  | 50 MB    | MP4, WebM, MOV            |

## Presigned Upload URLs

For large files or client-side uploads, use presigned URLs to upload directly to storage without proxying through the API:

```bash theme={null}
# 1. Request a signed upload URL
curl -X POST https://app.quiz-quail.com/api/v1/media/signed-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "background-video.mp4",
    "contentType": "video/mp4"
  }'
```

```json theme={null}
{
  "signedUrl": "https://storage.quizquail.com/media/upload?token=...",
  "storagePath": "user-123/1742083260-x9y8z7.mp4",
  "publicUrl": "https://storage.quizquail.com/media/user-123/1742083260-x9y8z7.mp4"
}
```

```bash theme={null}
# 2. Upload the file directly to the signed URL
curl -X PUT "SIGNED_URL_FROM_STEP_1" \
  -H "Content-Type: video/mp4" \
  --data-binary @./background-video.mp4
```

The `publicUrl` is immediately usable in question content fields like `imageUrl`, `videoUrl`, and `audioUrl`.

## Search External Sources

Search free media from Pexels, Freesound, and Wikipedia without uploading:

```bash theme={null}
curl -X POST https://app.quiz-quail.com/api/v1/media/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mountains",
    "source": "pexels_images",
    "count": 6
  }'
```

### Available Sources

| Source          | Content Type | Description                           |
| --------------- | ------------ | ------------------------------------- |
| `pexels_images` | Images       | Free stock photos from Pexels         |
| `pexels_videos` | Videos       | Free stock videos from Pexels         |
| `freesound`     | Audio        | Creative Commons audio from Freesound |
| `wikipedia`     | Images       | Public domain images from Wikipedia   |

The `count` parameter controls how many results to return (1-30, default: 12).

Search results return URLs you can use directly in question content or download and re-upload to your media library.

## List Your Media

```bash theme={null}
curl "https://app.quiz-quail.com/api/v1/media?limit=20&mime_type=image" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

| Parameter   | Default | Description                                                               |
| ----------- | ------- | ------------------------------------------------------------------------- |
| `limit`     | 20      | Items per page (1-100)                                                    |
| `mime_type` | —       | Filter by type: `image`, `video`, `audio`, or exact MIME like `image/png` |
| `cursor`    | —       | Pagination cursor from previous response                                  |

Supports [cursor-based pagination](/pagination). Each item includes a `url` field with the public download URL.

## Delete Media

```bash theme={null}
curl -X DELETE https://app.quiz-quail.com/api/v1/media/media-001 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Returns `204 No Content`. This deletes both the storage file and the database record. Media that is currently referenced by questions is not blocked from deletion, but those questions will show broken media.

## Example: Upload an Image and Use It in a Question

```bash theme={null}
# 1. Upload the image
curl -X POST https://app.quiz-quail.com/api/v1/media \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@./eiffel-tower.jpg"

# Response includes:
# "url": "https://storage.quizquail.com/media/user-123/1742083260-a1b2c3.jpg"

# 2. Create an image question using the uploaded URL
curl -X POST \
  https://app.quiz-quail.com/api/v1/quizzes/quiz-001/rounds/round-001/questions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question_type": "image",
    "content": {
      "text": "Which landmark is this?",
      "imageUrl": "https://storage.quizquail.com/media/user-123/1742083260-a1b2c3.jpg",
      "options": ["Big Ben", "Eiffel Tower", "Colosseum", "Statue of Liberty"],
      "correctOptionIndex": 1
    }
  }'
```