ガイド
ファイルアップロード
ファイルを一度アップロードし、Messages、Responses、画像生成、動画生成のリクエストで ID を指定して参照します。
ファイルを一度アップロードすれば、以降はモデルリクエストで ID を指定して参照できます。同じバイト列を base64 で送り直したり、ファイルを公開 URL でホストしたりする必要はありません。
ファイル ID は Messages、Responses、画像生成、動画生成で使えます。Chat Completions では使えません。
開始前に
- API key。認証を参照してください。
- Base URL:
https://openapi.felo.ai。 - 送信するファイルの種類を受け付けるモデル。モデルの対応状況を確認するを参照してください。
クイックスタート
1. ファイルをアップロードする
curl "https://openapi.felo.ai/api/v1/files" \
-H "Authorization: Bearer ${FELO_API_KEY}" \
-F "file=@./report.pdf"アップロードに成功すると、HTTP 200 とファイルのメタデータが返ります。
{
"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. リクエストで参照する
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 で書くと次のとおりです。
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 以降の場合:
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
{
"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
| ファイル | コンテンツブロック |
|---|---|
{"type": "input_file", "file_id": "..."} | |
| 画像 | {"type": "input_image", "file_id": "...", "detail": "auto"} |
file_id を持つブロックに、URL や base64 データを同時に含めることはできません。
画像生成
{
"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 レスポンス、ポーリングについては画像生成を参照してください。
動画生成
最初のフレームと最後のフレームは frame_images に指定します。
{
"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 に指定します。各エントリには、メディアの種類に対応するロケーターを使います。
{
"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を渡してください。 - ファイルを参照するリクエストは、失敗しても別のチャネルに切り替わりません。エラーを確認せずに別のチャネルで再試行しないでください。
- ファイルを参照しているすべてのタスクが終端状態になるまで、そのファイルを残しておいてください。先に削除するとタスクが失敗する場合があります。
モデルの対応状況を確認する
保存済みのファイルが、すべてのモデルで自動的に使えるわけではありません。モデルは公開カタログで対応する入力モダリティを宣言している必要があります。
curl -s "https://openapi.felo.ai/api/platform/model-catalog/model?model=claude-haiku-4-5" \
| jq '.data.input_modalities'["text", "image", "file"]| 送信するもの | input_modalities に必要な値 |
|---|---|
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 ではなく、ファイルの内容から判定されます。
| 種類 | 形式 | 参照できる場所 |
|---|---|---|
| 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 を使えません。
ファイルを一覧表示する
curl "https://openapi.felo.ai/api/v1/files?limit=100" \
-H "Authorization: Bearer ${FELO_API_KEY}"{
"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 件取得する
curl "https://openapi.felo.ai/api/v1/files/${FILE_ID}" \
-H "Authorization: Bearer ${FELO_API_KEY}"ファイルを削除する
curl -X DELETE "https://openapi.felo.ai/api/v1/files/${FILE_ID}" \
-H "Authorization: Bearer ${FELO_API_KEY}"{"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 | ファイルオブジェクト |
GET | /api/v1/files | ファイルのページ |
GET | /api/v1/files/{file_id} | ファイルオブジェクト |
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 エラーエンベロープを使います。
{
"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 にこれらのコードのいずれかが入ります。
認証、残高、レート制限のエラーはエラー、レート制限、リトライを参照してください。