---
title: "이미지 업로드 URL 발급"
description: "입력으로 사용할 이미지(contextImages 항목, 동영상 프레임, 인페인트 베이스 이미지 등)를 업로드하는 1단계입니다."
canonical: "https://platform.pixai.art/ko/docs/api-v2/media/getImageUploadUrl"
last-updated: "2026-11-02"
---

# 이미지 업로드 URL 발급

입력으로 사용할 이미지(`contextImages` 항목, 동영상 프레임, 인페인트 베이스 이미지 등)를 업로드하는 1단계입니다.



1. 이 엔드포인트를 호출하여 `uploadUrl`과 `externalId`를 받습니다.
2. 원시 이미지 바이트를 HTTP `PUT`으로 `uploadUrl`에 보내고, 파일의 실제 `Content-Type`(예: `image/png`)을 지정합니다. 멀티파트 폼은 사용하지 마세요.
3. `externalId`로 `POST /v2/media/image/register`를 호출합니다. 응답의 `id`가 다른 엔드포인트에 전달할 미디어 ID입니다.

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

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

- `isEphemeral` (boolean, optional)
  파일을 단기 생성 입력용으로 표시합니다. 임시(ephemeral) 파일은 비공개이며, URL은 서명되어 있고 만료됩니다.
  Default: `false`.

Example:

```json
{}
```

### Example (cURL)

```bash
# 1. 업로드 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. 바이트 업로드
curl -X PUT "$URL" -H "Content-Type: image/png" --data-binary @input.png

# 3. 등록하고 미디어 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`
  업로드 대상.
  Body fields:
  - `uploadUrl` (string, required)
    사전 서명된 URL입니다. 원시 파일 바이트를 파일의 `Content-Type`과 함께 이 URL에 `PUT`하세요.
  - `externalId` (string, required)
    업로드 후 대응하는 `register` 엔드포인트에 전달하세요.
- `401`
  `UNAUTHORIZED`: API 키를 보내지 않았습니다. 잘못되었거나 폐기되었거나 만료된 키에는 숫자 `code`를 가진 `{"message": "invalid token", "code": 40100001}`이 반환됩니다.