---
title: "Upload an image or video"
description: "Upload an image or video and receive a media ID that identifies the stored file."
canonical: "https://platform.pixai.art/en/docs/api/media/uploadMedia"
last-updated: "2026-11-02"
---

# Upload an image or video

Upload an image or video and receive a media ID that identifies the stored file.



## POST https://api.pixai.art/v1/media/upload

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

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

### Request body (`image/png`)

### Request body (`image/jpeg`)

### Request body (`image/webp`)

### Request body (`image/gif`)

### Request body (`video/mp4`)

### Example (cURL)

```bash
curl -X POST https://api.pixai.art/v1/media/upload \
  -H "Authorization: Bearer $PIXAI_API_KEY" \
  -H "Content-Type: image/png" \
  --data-binary @reference.png
```

### Responses

- `200`
  The uploaded media.
  Body fields:
  - `id` (string, required)
    The unique identifier for the media. Use this value as the `mediaId` path parameter of the other media endpoints.
  - `type` (string, required)
    The media type that the server detected.
    Allowed values: `IMAGE`, `VIDEO`.
  - `urls` (object[], optional)
    The available URLs for the media. Image uploads return this field.
  - `urls[].variant` (string, required)
    The URL variant.
    Allowed values: `PUBLIC`, `THUMBNAIL`, `STILL_THUMBNAIL`.
  - `urls[].url` (string, required)
  - `width` (integer, optional)
    The width of the image in pixels.
  - `height` (integer, optional)
    The height of the image in pixels.
  - `imageType` (string, optional)
    The stored MIME type of the image, for example `image/png`.
  - `fileUrl` (string, optional)
    The file URL. Video uploads return this field.
  - `duration` (number, optional)
    The duration in seconds. Video uploads return this field.
  - `thumbnailUrl` (string, optional)
    The thumbnail URL. Video uploads return this field.
  - `hlsUrl` (string, optional)
    The HLS playlist URL. Video uploads return this field.
  - `size` (integer, optional)
    The file size in bytes. Video uploads return this field.
- `400`
  The `Content-Type` header is absent, the `Content-Length` header is absent, the body length is different from `Content-Length`, or the content type is neither an image nor a video.
- `401`
  The API key is absent or invalid.