---
title: "업로드한 이미지 등록"
description: "이미지 업로드의 3단계로, 업로드한 파일을 미디어 항목으로 만듭니다. uploadUrl로의 PUT이 성공한 후 호출하세요. 반환된 id가 다른 엔드포인트에 전달할 미디어 ID입니다."
canonical: "https://platform.pixai.art/ko/docs/api-v2/media/registerImage"
last-updated: "2026-11-02"
---

# 업로드한 이미지 등록

이미지 업로드의 3단계로, 업로드한 파일을 미디어 항목으로 만듭니다. `uploadUrl`로의 `PUT`이 성공한 후 호출하세요. 반환된 `id`가 다른 엔드포인트에 전달할 미디어 ID입니다.



## 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.ko.yaml

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

- `externalId` (string, required)
  `POST /v2/media/image/upload-url`이 반환한 `externalId`입니다.
- `isEphemeral` (boolean, optional)
  `upload-url`에 보낸 값과 같은 값을 보내세요.

Example:

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

### Responses

- `200`
  등록된 이미지. 몇 초 뒤 처리가 끝나기 전까지는 `width`와 `height`가 `0`일 수 있습니다. 필요하면 `GET /v2/media/batch`에서 읽으세요.
  Body fields:
  - `id` (string, required)
    미디어 ID.
  - `type` (string, required)
    Allowed values: `IMAGE`, `VIDEO`, `AUDIO`.
  - `urls` (object[], optional)
    변형별 이미지 URL입니다. `PUBLIC`이 원본 크기 이미지입니다.
  - `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입니다(동영상의 MP4 등).
  - `hlsUrl` (string | null, optional)
    동영상의 HLS 스트림. 생성된 동영상에서는 `null`인 경우가 많으므로 `fileUrl`을 사용하세요.
  - `thumbnailUrl` (string | null, optional)
    동영상의 포스터 이미지. 생성된 동영상에서는 `null`인 경우가 많으며, 포스터는 작업의 `outputs.mediaIds`에 있습니다.
  - `duration` (number | null, optional)
    동영상 또는 오디오 파일의 길이(초). 생성된 동영상에서는 `0`일 수 있습니다.
- `401`
  `UNAUTHORIZED`: API 키를 보내지 않았습니다. 잘못되었거나 폐기되었거나 만료된 키에는 숫자 `code`를 가진 `{"message": "invalid token", "code": 40100001}`이 반환됩니다.