# ファイルアップロード

ファイルを一度アップロードし、Messages、Responses、画像生成、動画生成のリクエストで ID を指定して参照します。

ファイルを一度アップロードすれば、以降はモデルリクエストで ID を指定して参照できます。同じバイト列を base64 で送り直したり、ファイルを公開 URL でホストしたりする必要はありません。

ファイル ID は Messages、Responses、画像生成、動画生成で使えます。Chat Completions では使えません。

## 開始前に

- API key。[認証](https://openapi.felo.ai/ja/docs/authentication.md)を参照してください。
- Base URL: `https://openapi.felo.ai`。
- 送信するファイルの種類を受け付けるモデル。[モデルの対応状況を確認する](#対応状況-確認)を参照してください。

## クイックスタート

### 1. ファイルをアップロードする

```bash
curl "https://openapi.felo.ai/api/v1/files" \
  -H "Authorization: Bearer ${FELO_API_KEY}" \
  -F "file=@./report.pdf"
```

アップロードに成功すると、HTTP `200` とファイルのメタデータが返ります。

```json
{
  "id": "felo_file_0179...",
  "type": "file",
  "source": "upload",
  "filename": "report.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 482113,
  "created_at": "2026-11-10T02:25:41Z",
  "downloadable": false
}
```

`id` を保存してください。不透明な文字列として扱い、組み立てたり解析したりしないでください。

### 2. リクエストで参照する

```bash
curl "https://openapi.felo.ai/api/v1/responses" \
  -H "Authorization: Bearer ${FELO_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "input": [
      {
        "role": "user",
        "content": [
          {"type": "input_file", "file_id": "felo_file_0179..."},
          {"type": "input_text", "text": "Summarize the attached report."}
        ]
      }
    ]
  }'
```

同じ 2 つのステップを Python で書くと次のとおりです。

```python
import os

import requests

BASE = "https://openapi.felo.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['FELO_API_KEY']}"}


def upload(path: str) -> str:
    with open(path, "rb") as file:
        response = requests.post(
            f"{BASE}/api/v1/files",
            headers=HEADERS,
            files={"file": file},
            timeout=300,
        )
    response.raise_for_status()
    return response.json()["id"]


file_id = upload("./report.pdf")

response = requests.post(
    f"{BASE}/api/v1/responses",
    headers=HEADERS,
    json={
        "model": "gpt-5.5",
        "input": [
            {
                "role": "user",
                "content": [
                    {"type": "input_file", "file_id": file_id},
                    {"type": "input_text", "text": "Summarize the attached report."},
                ],
            }
        ],
    },
    timeout=120,
)
response.raise_for_status()
print(response.json())
```

Node.js 20 以降の場合:

```javascript
import { openAsBlob } from "node:fs";
import { basename } from "node:path";

const BASE = "https://openapi.felo.ai";
const headers = { Authorization: `Bearer ${process.env.FELO_API_KEY}` };

async function upload(path) {
  const form = new FormData();
  form.append("file", await openAsBlob(path), basename(path));
  const response = await fetch(`${BASE}/api/v1/files`, { method: "POST", headers, body: form });
  if (!response.ok) throw new Error(`Upload failed: ${response.status} ${await response.text()}`);
  return (await response.json()).id;
}

const fileId = await upload("./report.pdf");
```

### アップロードのルール

- 本文は `multipart/form-data` で、`file` という名前のパートを 1 つだけ含めます。`purpose` を含め、ほかのパートがあると `invalid_file` で拒否されます。
- `Content-Type` は HTTP クライアントに設定させてください。手動で設定すると multipart boundary が失われます。
- アップロード URL にクエリパラメータを付けないでください。
- SDK の Files ヘルパーではなく、HTTP でアップロードしてください。OpenAI SDK の `files.create()` は常に `purpose` を送信するため、この endpoint を呼び出せません。
- タイムアウトや切断が起きたアップロードでも、ファイルは保存されている場合があります。再アップロードする前にファイル一覧を確認してください。

## ファイル ID を使える場所

| Endpoint | ファイルの種類 | 必要な入力モダリティ | フィールド |
|---|---|---|---|
| `POST /api/v1/messages` | PDF、画像 | `file`、`image` | `messages[].content[]` |
| `POST /api/v1/responses` | PDF、画像 | `file`、`image` | `input[].content[]` |
| `POST /api/v1/images/generations` | 画像 | `image` | `input_references[]` |
| `POST /api/v1/videos/generations` | 画像 | `image` | `frame_images[]` |
| `POST /api/v1/videos/generations` | 画像、MP4、音声 | `image`、`video`、`audio` | `input_references[]` |
| `POST /api/v1/chat/completions` | 非対応 | | |

### Messages

```json
{
  "model": "claude-haiku-4-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "document", "source": {"type": "file", "file_id": "felo_file_0179..."}},
        {"type": "text", "text": "Summarize the attached report."}
      ]
    }
  ]
}
```

画像の場合は `{"type": "image", "source": {"type": "file", "file_id": "..."}}` を使います。

### Responses

| ファイル | コンテンツブロック |
|---|---|
| PDF | `{"type": "input_file", "file_id": "..."}` |
| 画像 | `{"type": "input_image", "file_id": "...", "detail": "auto"}` |

`file_id` を持つブロックに、URL や base64 データを同時に含めることはできません。

### 画像生成

```json
{
  "model": "gemini-3-pro-image",
  "prompt": "Keep the product and framing. Replace the background with a sunlit marble countertop.",
  "input_references": [
    {"type": "image_url", "image_url": {"file_id": "felo_file_0179..."}}
  ]
}
```

リクエストのその他の部分、`202` レスポンス、ポーリングについては[画像生成](https://openapi.felo.ai/ja/docs/guides/image-generation.md)を参照してください。

### 動画生成

最初のフレームと最後のフレームは `frame_images` に指定します。

```json
{
  "model": "YOUR_VIDEO_MODEL",
  "prompt": "The camera slowly pushes in. Keep the colors and composition.",
  "duration": 5,
  "resolution": "720p",
  "frame_images": [
    {
      "type": "image_url",
      "frame_type": "first_frame",
      "image_url": {"file_id": "felo_file_0179..."}
    }
  ]
}
```

最後のフレームを指定するには、`"frame_type": "last_frame"` のエントリをもう 1 つ追加します。最後のフレームを使うには最初のフレームが必要です。

参考素材は `input_references` に指定します。各エントリには、メディアの種類に対応するロケーターを使います。

```json
{
  "input_references": [
    {"type": "image_url", "image_url": {"file_id": "felo_file_IMAGE"}},
    {"type": "video_url", "video_url": {"file_id": "felo_file_VIDEO"}},
    {"type": "audio_url", "audio_url": {"file_id": "felo_file_AUDIO"}}
  ]
}
```

モデルが受け付ける組み合わせは、モデルとチャネルによって異なります。`frame_images` と `input_references` を同じリクエストで使うことはできません。

### ロケーターのルール

- 画像と動画のリクエストでは、`image_url`、`video_url`、`audio_url` の各オブジェクトに `file_id` か `url` のどちらか一方だけを含め、ほかのフィールドは含めません。
- 1 つの配列に、`file_id` を使うエントリと `url` を使うエントリを混在させることができます。
- 画像生成と動画生成は、自分でアップロードしたファイルだけを受け付けます。生成された画像を再利用するには、その出力の `url` を渡してください。
- ファイルを参照するリクエストは、失敗しても別のチャネルに切り替わりません。エラーを確認せずに別のチャネルで再試行しないでください。
- ファイルを参照しているすべてのタスクが終端状態になるまで、そのファイルを残しておいてください。先に削除するとタスクが失敗する場合があります。

## モデルの対応状況を確認する

保存済みのファイルが、すべてのモデルで自動的に使えるわけではありません。モデルは公開カタログで対応する入力モダリティを宣言している必要があります。

```bash
curl -s "https://openapi.felo.ai/api/platform/model-catalog/model?model=claude-haiku-4-5" \
  | jq '.data.input_modalities'
```

```json
["text", "image", "file"]
```

| 送信するもの | `input_modalities` に必要な値 |
|---|---|
| PDF | `file` |
| 画像 | `image` |
| MP4 | `video` |
| 音声ファイル | `audio` |

リストが空または存在しない場合、そのモデルではファイル ID が有効になっていません。この場合、リクエストは `file_model_unsupported` で失敗します。モデル名から対応状況を推測しないでください。

## 制限

| 制限 | 値 |
|---|---|
| アップロードサイズ | 1 ファイルあたり 100 MiB（104,857,600 バイト）。空のファイルは拒否される |
| モデルリクエスト 1 件あたりの参照バイト数 | 合計 50,000,000 バイト |
| モデルリクエスト 1 件あたりの参照数 | 100 |
| ファイル名の長さ | 255 文字 |

同じファイルを 2 回参照すると、リクエストの両方の制限に対して 2 回分として数えられます。50 MB から 100 MiB のファイルはアップロードできますが、モデルリクエストでは参照できません。モデルやチャネルによっては、より低い制限が適用される場合があります。

### ファイルの種類

種類は、拡張子やパートの `Content-Type` ではなく、ファイルの内容から判定されます。

| 種類 | 形式 | 参照できる場所 |
|---|---|---|
| PDF | PDF | Messages、Responses |
| 画像 | PNG、JPEG、GIF、WebP | Messages、Responses、画像生成、動画生成 |
| 動画 | MP4 | 動画生成 |
| 音声 | MP3、WAV、FLAC、OGG | 動画生成 |
| Office | DOCX、XLSX、PPTX | 保存のみ |
| テキスト | UTF-8 テキスト。`text/plain` として保存される | 保存のみ |

それ以外の内容は `invalid_file` で拒否されます。

### ファイル名

ファイル名に `<`、`>`、`:`、`"`、`|`、`?`、`*`、`\`、制御文字は使えません。`/` は区切り文字として使えますが、空のセグメント、`.`、`..` は使えません。

## ファイルを管理する

ファイルはアカウントに属します。アカウントのすべての API key から同じファイルが見えます。ほかのアカウントはあなたのファイル ID を使えません。

### ファイルを一覧表示する

```bash
curl "https://openapi.felo.ai/api/v1/files?limit=100" \
  -H "Authorization: Bearer ${FELO_API_KEY}"
```

```json
{
  "data": [
    {
      "id": "felo_file_0179...",
      "type": "file",
      "source": "upload",
      "filename": "report.pdf",
      "mime_type": "application/pdf",
      "size_bytes": 482113,
      "created_at": "2026-11-10T02:25:41Z",
      "downloadable": false
    }
  ],
  "first_id": "felo_file_0179...",
  "last_id": "felo_file_0179...",
  "cursor": "felo_file_0179...",
  "has_more": false
}
```

結果は古い順に並びます。`has_more` が `true` の場合は、返された `cursor` を渡して次のページを取得します。サーバー側の検索や種類によるフィルタはありません。

### ファイルを 1 件取得する

```bash
curl "https://openapi.felo.ai/api/v1/files/${FILE_ID}" \
  -H "Authorization: Bearer ${FELO_API_KEY}"
```

### ファイルを削除する

```bash
curl -X DELETE "https://openapi.felo.ai/api/v1/files/${FILE_ID}" \
  -H "Authorization: Bearer ${FELO_API_KEY}"
```

```json
{"id": "felo_file_0179...", "type": "file_deleted"}
```

削除はすぐに反映され、元に戻せません。`503` は削除が完了しなかったことを意味します。`DELETE` をもう一度送信してください。

### ダウンロード

アップロードしたファイルはダウンロードできません。`GET /api/v1/files/{file_id}/content` は `400 file_not_downloadable` を返します。また、アップロードレスポンスの `Location` ヘッダーはファイルのバイト列ではなくメタデータを指します。アップロードするものは、手元にコピーを残しておいてください。

生成されたメディアをダウンロードするには、タスクの `outputs` にある署名付き URL を使います。

## API リファレンス

すべての endpoint は `Authorization: Bearer YOUR_API_KEY` を使います。成功レスポンスは、エンベロープのないプレーンな JSON オブジェクトです。

| メソッド | パス | 戻り値 |
|---|---|---|
| `POST` | `/api/v1/files` | [ファイルオブジェクト](#section-5) |
| `GET` | `/api/v1/files` | [ファイルのページ](#一覧) |
| `GET` | `/api/v1/files/{file_id}` | [ファイルオブジェクト](#section-5) |
| `DELETE` | `/api/v1/files/{file_id}` | `{"id": "...", "type": "file_deleted"}` |
| `GET` | `/api/v1/files/{file_id}/content` | `400 file_not_downloadable` |

`POST`、`DELETE`、単一ファイルの `GET` は、クエリパラメータが付いていると `invalid_query` で拒否します。

### ファイルオブジェクト

| フィールド | 型 | 説明 |
|---|---|---|
| `id` | string | ファイル ID。`felo_file_` で始まる。`file_id` として使う |
| `type` | string | 常に `file` |
| `source` | string | 自分でアップロードしたファイルは `upload`、モデルの出力は `generated` |
| `filename` | string | アップロード時に送信された名前 |
| `mime_type` | string | 内容から判定された種類 |
| `size_bytes` | integer | バイト単位のサイズ |
| `created_at` | string | ISO 8601 形式の UTC タイムスタンプ |
| `downloadable` | boolean | アップロードしたファイルでは `false` |

### アップロードリクエスト

| パート | 必須 | 説明 |
|---|---|---|
| `file` | はい | ファイル本体。ファイル名付きの `multipart/form-data` ファイルパートとして送信する |

レスポンスには、ファイルのメタデータの URL を示す `Location` ヘッダーが含まれます。

### 一覧のパラメータ

| パラメータ | デフォルト | 説明 |
|---|---|---|
| `limit` | `100` | ページサイズ。1 から 1000 |
| `cursor` | | 前のページの `cursor` の値 |
| `after`、`after_id` | | `cursor` のエイリアス。3 つのうち 1 つだけ送信する |
| `order` | `asc` | `asc` のみ対応 |

| レスポンスフィールド | 型 | 説明 |
|---|---|---|
| `data` | array | ファイルオブジェクト。古い順 |
| `first_id` | string または null | ページ内の最初のファイルの ID |
| `last_id` | string または null | ページ内の最後のファイルの ID |
| `cursor` | string または null | 次のページを取得するときに `cursor` として渡す値 |
| `has_more` | boolean | 次のページがあるかどうか |

## エラー

Files の endpoint、Responses、画像生成、動画生成は OpenAI エラーエンベロープを使います。

```json
{
  "error": {
    "message": "This model does not accept this attachment type",
    "type": "invalid_request_error",
    "param": "frame_images.0.image_url",
    "code": "file_model_unsupported"
  }
}
```

Files の endpoint からのエラーでは `param` は `null` です。Messages は Anthropic のエラー形式を返し、`error.code` はありません。request ID は `X-Request-Id` レスポンスヘッダーにあります。

ファイルのアップロード時や管理時のエラー:

| HTTP | `error.code` | 意味 |
|---|---|---|
| 400 | `invalid_content_type` | 本文が `multipart/form-data` ではない |
| 400 | `invalid_file` | `file` パートがない、余分なパートがある、ファイルが空、または非対応の内容 |
| 400 | `invalid_filename` | ファイル名が長すぎる、または使用できない文字を含む |
| 413 | `file_too_large` | ファイルが 100 MiB を超えている |
| 400 | `invalid_query` | 非対応のクエリパラメータがある、または `order` が `asc` 以外 |
| 400 | `invalid_limit` | `limit` が 1 から 1000 の範囲外 |
| 400 | `invalid_cursor` | カーソルの形式が不正、または複数のカーソルが送信された |
| 400 | `file_not_downloadable` | `/content` がリクエストされた |
| 404 | `file_not_found` | ファイルが存在しない、削除済み、または別のアカウントのもの |
| 503 | `file_storage_unavailable` | ファイルストレージが一時的に利用できない。後で再試行する |
| 503 | `file_upload_expired` | アップロードが時間内に完了しなかった。ファイルを再アップロードする |

モデルリクエストでファイルを参照するときのエラー:

| HTTP | `error.code` | 意味 |
|---|---|---|
| 400 | `invalid_file_input` | ID の形式が不正、1 つのロケーターに `file_id` と `url` の両方がある、または参照が 100 件を超えている |
| 400 | `unsupported_file_type` | ファイルの種類が位置と合っていない。例: ドキュメントブロックに MP4 |
| 400 | `file_model_unsupported` | モデルが必要な入力モダリティを宣言していない |
| 400 | `file_input_too_large` | 参照したファイルの合計が 50,000,000 バイトを超えている |
| 400 | `file_protocol_unsupported` | ファイル ID を Chat Completions に送った |
| 404 | `file_not_found` | ファイルが存在しない、削除済み、別のアカウントのもの、または生成されたファイルを画像生成や動画生成に送った |

画像生成と動画生成では、`202` の後にファイルが原因で失敗することもあります。その場合、タスクは `failed` で終了し、`error.code` にこれらのコードのいずれかが入ります。

認証、残高、レート制限のエラーは[エラー、レート制限、リトライ](https://openapi.felo.ai/ja/docs/guides/errors-and-limits.md)を参照してください。

## 関連

- [プロトコルと SDK](https://openapi.felo.ai/ja/docs/guides/protocols.md)
- [画像生成](https://openapi.felo.ai/ja/docs/guides/image-generation.md)
- [非同期タスク](https://openapi.felo.ai/ja/docs/guides/async-tasks.md)
- [Model API リファレンス](https://openapi.felo.ai/ja/docs/model-api)
