Felo API PlatformFelo API Platform

ガイド

ファイルアップロード

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

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

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

開始前に

クイックスタート

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/messagesPDF、画像file、imagemessages[].content[]
POST /api/v1/responsesPDF、画像file、imageinput[].content[]
POST /api/v1/images/generations画像imageinput_references[]
POST /api/v1/videos/generations画像imageframe_images[]
POST /api/v1/videos/generations画像、MP4、音声image、video、audioinput_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

ファイルコンテンツブロック
PDF{"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 に必要な値
PDFfile
画像image
MP4video
音声ファイル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 ではなく、ファイルの内容から判定されます。

種類形式参照できる場所
PDFPDFMessages、Responses
画像PNG、JPEG、GIF、WebPMessages、Responses、画像生成、動画生成
動画MP4動画生成
音声MP3、WAV、FLAC、OGG動画生成
OfficeDOCX、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}/content400 file_not_downloadable

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

ファイルオブジェクト

フィールド型説明
idstringファイル ID。felo_file_ で始まる。file_id として使う
typestring常に file
sourcestring自分でアップロードしたファイルは upload、モデルの出力は generated
filenamestringアップロード時に送信された名前
mime_typestring内容から判定された種類
size_bytesintegerバイト単位のサイズ
created_atstringISO 8601 形式の UTC タイムスタンプ
downloadablebooleanアップロードしたファイルでは false

アップロードリクエスト

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

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

一覧のパラメータ

パラメータデフォルト説明
limit100ページサイズ。1 から 1000
cursor前のページの cursor の値
after、after_idcursor のエイリアス。3 つのうち 1 つだけ送信する
orderascasc のみ対応
レスポンスフィールド型説明
dataarrayファイルオブジェクト。古い順
first_idstring または nullページ内の最初のファイルの ID
last_idstring または nullページ内の最後のファイルの ID
cursorstring または null次のページを取得するときに cursor として渡す値
has_moreboolean次のページがあるかどうか

エラー

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 レスポンスヘッダーにあります。

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

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

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

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

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

認証、残高、レート制限のエラーはエラー、レート制限、リトライを参照してください。

関連

ヘルプが必要ですか?

  • API・請求・アカウントのご質問はサポートへ。
  • Discord で Felo の開発者と交流できます。
  • 更新履歴 をご覧ください。
  • ボリューム価格や購買についてのご相談は営業窓口へ。
  • LLM での構築をお考えですか?llms.txt をご覧ください。