---
title: "Request pre-signed URLs to upload files"
method: POST
path: "/v1/ai/uploads/request-url"
tags: ["uploads"]
---

# Request pre-signed URLs to upload files

`POST /v1/ai/uploads/request-url`

## Request

- Base URL: `https://api.magnific.com`
- URL: `https://api.magnific.com/v1/ai/uploads/request-url`
- Auth: API key in header `x-magnific-api-key`

Request one or more pre-signed URLs to upload your own files (image, video or audio) and reference them in other AI endpoints.

Flow:
1. Call this endpoint with the `content_type` of each file. You get, per file, an `upload_url` (pre-signed PUT), an opaque `file_id`, and a readable `asset_url`.
2. PUT the raw file bytes to each `upload_url`, including ALL the returned `headers`. The `upload_url` expires quickly (`expires_in`).
3. Reference the upload by `file_id` (preferred on AI endpoints) or by `asset_url` (a plain URL usable anywhere a URL is accepted).

## Request body

- UploadRequestBody
  - `files` UploadFileRequest[], required: List of files to generate upload URLs for
    - `content_type` 'image/png' | 'image/jpeg' | 'image/webp' | 'video/mp4' | 'video/webm' | 'video/quicktime' | 'audio/mpeg' | 'audio/wav' | 'audio/mp4' | 'audio/webm' | 'audio/ogg', required: MIME type of the file to upload

## Response `200`

OK - Pre-signed upload URLs generated.

- UploadResponse
  - `files` UploadFileResponse[], required
    - `upload_url` string, uri, required: Pre-signed URL for PUT upload. Send the raw file bytes including ALL the headers returned in 'headers'.
    - `file_id` string, required: Opaque identifier of the uploaded file. Use this value in reference_images, image_url, video_url, or similar fields. It is NOT a URL and can only be used through the API by the same user that uploaded it.
    - `headers` object, required: Headers that MUST be included in the PUT request (they are part of the URL signature).
    - `expires_in` integer, required: Seconds until the upload_url expires
    - `asset_url` string, uri, required: Readable URL for the uploaded file (image, video or audio), serving the original file. Valid once the PUT to upload_url completes. Use it as image_url/video_url/audio_url/reference in any endpoint that accepts a URL. Prefer file_id on AI endpoints when available.
    - `asset_url_expires_in` integer, required: Seconds until asset_url expires (counted from this response, not from upload).

## Other responses

- `400`: Bad Request - The server could not understand the request due to invalid syntax.
- `401`: Unauthorized - The client must authenticate itself to get the requested response.
- `500`: Internal Server Error - The server has encountered a situation it doesn't know how to handle.
- `503`: Service Unavailable

---

[API](https://skmtc.dev/magnific/apis/magnific-api.md) · [All operations](https://skmtc.dev/magnific/apis/magnific-api/llms.txt) · [OpenAPI document](https://skmtc.dev/magnific/apis/magnific-api/revisions/60711fb082c7?raw)