---
title: "アップロードした画像の登録"
description: "画像アップロードのステップ 3 です。アップロードしたファイルをメディアアイテムにします。uploadUrl への PUT が成功した後に呼び出してください。返される id が、他のエンドポイントに渡すメディア ID です。"
canonical: "https://platform.pixai.art/ja/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.ja.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}` が返ります。