---
title: "Register an uploaded image"
description: "Step 3 of uploading an image: turns the uploaded file into a media item. Call it after the PUT to uploadUrl has succeeded. The returned id is the media ID to pass to other endpoints."
canonical: "https://platform.pixai.art/en/docs/api-v2/media/registerImage"
last-updated: "2026-11-02"
---

# Register an uploaded image

Step 3 of uploading an image: turns the uploaded file into a media item. Call it after the `PUT` to `uploadUrl` has succeeded. The returned `id` is the media ID to pass to other endpoints.



## POST https://api.pixai.art/v2/media/image/register

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`)

- `externalId` (string, required)
  The `externalId` returned by `POST /v2/media/image/upload-url`.
- `isEphemeral` (boolean, optional)
  Send the same value you sent to `upload-url`.

Example:

```json
{
  "externalId": "3f2b8c1e-6a4d-4f6e-9b1a-2c7d5e8f9a01"
}
```

### Responses

- `200`
  The registered image. `width` and `height` can be `0` until processing finishes a few seconds later; read them from `GET /v2/media/batch` if you need them.
  Body fields:
  - `id` (string, required)
    The media ID.
  - `type` (string, required)
    Allowed values: `IMAGE`, `VIDEO`, `AUDIO`.
  - `urls` (object[], optional)
    Image URLs by variant. `PUBLIC` is the full image.
  - `urls[].variant` (string, optional)
    Allowed values: `PUBLIC`, `THUMBNAIL`, `STILL_THUMBNAIL`.
  - `urls[].url` (string, optional)
  - `width` (number | null, optional)
  - `height` (number | null, optional)
  - `fileUrl` (string | null, optional)
    URL of the file itself, e.g. the MP4 of a video.
  - `hlsUrl` (string | null, optional)
    HLS stream of a video. Often `null` for generated videos; use `fileUrl`.
  - `thumbnailUrl` (string | null, optional)
    Poster image of a video. Often `null` for generated videos; the task's `outputs.mediaIds` holds the poster.
  - `duration` (number | null, optional)
    Length of a video or audio file in seconds. Can be `0` for generated videos.
- `401`
  `UNAUTHORIZED`: no API key was sent. An invalid, revoked or expired key answers `{"message": "invalid token", "code": 40100001}` instead, with a numeric `code`.