Skip to main content

​
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: 
curl -X POST https://app.quiz-quail.com/api/v1/media \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@./eiffel-tower.jpg"

{
  "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

TypeMax SizeAllowed Formats
Images10 MBJPEG, PNG, GIF, WebP, SVG
Audio10 MBMP3, WAV, OGG, M4A
Video50 MBMP4, 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: 
# 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"
  }'

{
  "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"
}

# 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: 
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

SourceContent TypeDescription
pexels_imagesImagesFree stock photos from Pexels
pexels_videosVideosFree stock videos from Pexels
freesoundAudioCreative Commons audio from Freesound
wikipediaImagesPublic 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

curl "https://app.quiz-quail.com/api/v1/media?limit=20&mime_type=image" \
  -H "Authorization: Bearer YOUR_API_KEY"
ParameterDefaultDescription
limit20Items 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. Each item includes a url field with the public download URL.

​
Delete Media

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

# 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
    }
  }'