---
title: "画像のアップロード URL の取得"
description: "入力として使う画像（contextImages の要素、動画のフレーム、インペイントのベース画像など）をアップロードする手順のステップ 1 です。"
canonical: "https://platform.pixai.art/ja/docs/api-v2/media/getImageUploadUrl"
last-updated: "2026-11-02"
---

# 画像のアップロード URL の取得

入力として使う画像（`contextImages` の要素、動画のフレーム、インペイントのベース画像など）をアップロードする手順のステップ 1 です。



1. このエンドポイントを呼び出して `uploadUrl` と `externalId` を取得します。
2. 画像の生バイトを、ファイルの実際の `Content-Type`（例: `image/png`）を付けて HTTP `PUT` で `uploadUrl` に送信します。マルチパートフォームは使用しないでください。
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.ja.yaml

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

- `isEphemeral` (boolean, optional)
  ファイルを短期間だけ使う生成入力としてマークします。エフェメラルファイルは非公開で、その 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` を付けて、生のファイルバイトを `PUT` してください。
  - `externalId` (string, required)
    アップロード後、対応する `register` エンドポイントにこの値を渡してください。
- `401`
  `UNAUTHORIZED`: API キーが送られていません。無効、失効済み、期限切れのキーの場合は、数値の `code` を持つ `{"message": "invalid token", "code": 40100001}` が返ります。