---
title: "Get an upload URL for an image"
description: "Step 1 of uploading an image you want to use as an input, for example a contextImages entry, a video frame or an inpaint base image."
canonical: "https://platform.pixai.art/en/docs/api-v2/media/getImageUploadUrl"
last-updated: "2026-11-02"
---

# Get an upload URL for an image

Step 1 of uploading an image you want to use as an input, for example a `contextImages` entry, a video frame or an inpaint base image.



1. Call this endpoint to get `uploadUrl` and `externalId`.
2. Send the raw image bytes to `uploadUrl` with an HTTP `PUT` and the file's real `Content-Type` (for example `image/png`). Do not use a multipart form.
3. Call `POST /v2/media/image/register` with the `externalId`. Its `id` is the media ID you pass to other endpoints.

## POST https://api.pixai.art/v2/media/image/upload-url

Authentication: send your API key as `Authorization: Bearer <API key>`.

Machine-readable OpenAPI spec: https://platform.pixai.art/openapi-spec.v2.yaml

### Request body (`application/json`)

- `isEphemeral` (boolean, optional)
  Mark the file as a short-lived generation input. Ephemeral files are private, and their URLs are signed and expire.
  Default: `false`.

Example:

```json
{}
```

### Example (cURL)

```bash
# 1. Get an upload URL
UPLOAD=$(curl -s -X POST https://api.pixai.art/v2/media/image/upload-url \
  -H "Authorization: Bearer $PIXAI_API_KEY" \
  -H "Content-Type: application/json" -d '{}')
URL=$(echo "$UPLOAD" | jq -r .uploadUrl)
EXTERNAL_ID=$(echo "$UPLOAD" | jq -r .externalId)

# 2. Upload the bytes
curl -X PUT "$URL" -H "Content-Type: image/png" --data-binary @input.png

# 3. Register it and read the media ID
curl -s -X POST https://api.pixai.art/v2/media/image/register \
  -H "Authorization: Bearer $PIXAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"externalId\": \"$EXTERNAL_ID\"}" | jq -r .id
```

### Responses

- `200`
  The upload target.
  Body fields:
  - `uploadUrl` (string, required)
    Presigned URL. `PUT` the raw file bytes to it with the file's `Content-Type`.
  - `externalId` (string, required)
    Pass this to the matching `register` endpoint after the upload.
- `401`
  `UNAUTHORIZED`: no API key was sent. An invalid, revoked or expired key answers `{"message": "invalid token", "code": 40100001}` instead, with a numeric `code`.