---
title: "이미지 또는 동영상 업로드"
description: "이미지 또는 동영상을 업로드하고 저장된 파일을 식별하는 미디어 ID를 받습니다."
canonical: "https://platform.pixai.art/ko/docs/api/media/uploadMedia"
last-updated: "2026-11-02"
---

# 이미지 또는 동영상 업로드

이미지 또는 동영상을 업로드하고 저장된 파일을 식별하는 미디어 ID를 받습니다.



## 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.ko.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`
  업로드된 미디어.
  Body fields:
  - `id` (string, required)
    미디어의 고유 식별자. 다른 미디어 엔드포인트의 `mediaId` 경로 파라미터에 이 값을 사용하세요.
  - `type` (string, required)
    서버가 판별한 미디어 타입.
    Allowed values: `IMAGE`, `VIDEO`.
  - `urls` (object[], optional)
    미디어에서 사용할 수 있는 URL. 이미지 업로드는 이 필드를 반환합니다.
  - `urls[].variant` (string, required)
    URL 배리언트.
    Allowed values: `PUBLIC`, `THUMBNAIL`, `STILL_THUMBNAIL`.
  - `urls[].url` (string, required)
  - `width` (integer, optional)
    이미지 너비(픽셀).
  - `height` (integer, optional)
    이미지 높이(픽셀).
  - `imageType` (string, optional)
    저장된 이미지의 MIME 타입입니다(예: `image/png`).
  - `fileUrl` (string, optional)
    파일 URL. 동영상 업로드는 이 필드를 반환합니다.
  - `duration` (number, optional)
    길이(초). 동영상 업로드는 이 필드를 반환합니다.
  - `thumbnailUrl` (string, optional)
    썸네일 URL. 동영상 업로드는 이 필드를 반환합니다.
  - `hlsUrl` (string, optional)
    HLS 플레이리스트 URL. 동영상 업로드는 이 필드를 반환합니다.
  - `size` (integer, optional)
    파일 크기(바이트). 동영상 업로드는 이 필드를 반환합니다.
- `400`
  `Content-Type` 헤더가 없거나, `Content-Length` 헤더가 없거나, 본문 길이가 `Content-Length`와 다르거나, 콘텐츠 타입이 이미지도 동영상도 아닙니다.
- `401`
  API 키가 없거나 유효하지 않습니다.