---
title: "Presign a reference-image upload"
method: POST
path: "/api/v1/uploads"
tags: ["Covers"]
---

# Presign a reference-image upload

`POST /api/v1/uploads`

## Request

- Base URL: `https://beyourcover.com`
- URL: `https://beyourcover.com/api/v1/uploads`
- Auth: HTTP bearer

Mints a short-lived (5 minute) presigned `PUT` URL for a reference image and returns the `upload_id` to pass to `POST /api/v1/covers/generate-reference`. FREE: consumes no credits. The storage key is server-generated — the client cannot choose it. Nothing about the object is trusted here: size, dimensions, and content-policy checks all run when a generation call consumes the `upload_id`, before any credit is reserved. Upload the bytes with a plain `PUT` to `upload_url` using the same `Content-Type` you declared.

## Request body

- object
  - `content_type` 'image/jpeg' | 'image/png' | 'image/webp', required: MIME type of the image you are going to upload.
  - `size_bytes` integer: Optional declared byte size; rejected early with `file_too_large` when it exceeds the limit returned in `max_bytes`.

## Response `200`

Presigned upload minted.

- UploadTicket
  - `upload_id` string, required: Opaque id for the staged upload. Pass it in reference_upload_ids.
  - `upload_url` string, uri, required: Presigned URL to PUT the image bytes to, using the declared Content-Type.
  - `expires_at` string, date-time, required: When upload_url stops working (5 minutes after minting).
  - `max_bytes` integer, required: Maximum accepted image size in bytes.
  - `allowed_types` string[], required: Accepted MIME types.

## Other responses

- `400`: `code`: `file_too_large` (declared size_bytes over the limit).
- `401`: Missing/malformed API key, unknown or inactive key, or inactive subscription detected during credit checks. `code`: `unauthorized`.
- `403`: The API key is valid but its owner has no active enterprise subscription. `code`: `forbidden`.
- `415`: Missing or unsupported `content_type`. `code`: `unsupported_media_type`.
- `500`: Server error. `code`: `internal_error`.

---

[API](https://skmtc.dev/beyourcover/apis/beyourcover-partner-api.md) · [All operations](https://skmtc.dev/beyourcover/apis/beyourcover-partner-api/llms.txt) · [OpenAPI document](https://skmtc.dev/beyourcover/apis/beyourcover-partner-api/revisions/82ad2c7c8ede?raw)