ファイル

Files API を使うと、アセットを一度アップロードして file_id で推論リクエストから参照できます。ターンごとにバイト列 (または base64) を再送する必要がありません。OpenAI Files API のシェイプと完全互換で、anthropic-version ヘッダ付きのリクエストには Anthropic Files API のシェイプを返します。これにより、公式の openai SDK と anthropic SDK のどちらも拡張なしで動作します。

POST   /v1/files
GET    /v1/files
GET    /v1/files/{file_id}
GET    /v1/files/{file_id}/content
DELETE /v1/files/{file_id}

ノート

v1 では purpose: "vision" (画像)、purpose: "video" (動画クリップ)、purpose: "audio" (音声クリップ)、purpose: "document" (PDF) をサポートしています。

制限

Purpose	単発の /v1/files	/v1/uploads 経由の合計	許可される MIME タイプ
vision	100 MiB	100 MiB	image/png, image/jpeg, image/webp, image/gif
video	100 MiB	8 GiB	video/mp4, video/webm, video/quicktime
audio	100 MiB	1 GiB	audio/wav, audio/x-wav, audio/mpeg, audio/mp3, audio/flac, audio/ogg, audio/webm, audio/mp4, audio/x-m4a
document	100 MiB	1 GiB	application/pdf

動画生成は GIF を受け付けません。/v1/videos のフレームと参照画像は PNG、JPEG、WebP のいずれかである必要があります（vision はチャット用に image/gif も受け付けます）。

ヒント

100 MiB を超えるファイルには Uploads API を使用してください — ファイルを 64 MiB 以下のパートに分割します。公式 openai SDK の client.uploads.upload(...) ヘルパーが、このチャンク分割フローを 1 回の呼び出しで実行します。

注意

document ファイルはアップロード時にページごとの画像に変換されるため、アップロード呼び出しは同期的です。PDF は 100 ページが上限で、超過した場合は 400 invalid_request_error を返します。推論時にはモデルが 1 ページにつき 1 枚の画像を受け取るため、対象モデルには vision capability が必要です。

アップロードのデフォルト有効期限は 30 日で、ファイルオブジェクトには常に expires_at が含まれます。期限切れ後の参照は 410 file_expired で失敗します。ファイルは DELETE によるソフト削除の対象でもあります。

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

POST /v1/files

multipart フォームアップロードです。

フィールド	型	必須	説明
file	file	はい	アセットのバイト列
purpose	string	いいえ	vision、video、audio、document のいずれか。制限値と参照可能なモデルを決定します。省略時はファイルの MIME タイプから推測されます — purpose を送信しない Anthropic SDK のアップロードでもそのまま動作します

使用例

Python

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.aiand.com/v1",
)

with open("photo.png", "rb") as f:
    file = client.files.create(file=f, purpose="vision")

print(file.id)  # → file-abc123...

JavaScript

import OpenAI, { toFile } from "openai";
import fs from "node:fs";

const client = new OpenAI({
  apiKey: "sk-your-api-key",
  baseURL: "https://api.aiand.com/v1",
});

const file = await client.files.create({
  file: await toFile(fs.createReadStream("photo.png"), "photo.png", {
    type: "image/png",
  }),
  purpose: "vision",
});

console.log(file.id); // → file-abc123...

curl

curl https://api.aiand.com/v1/files \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "file=@photo.png" \
  -F "purpose=vision"

MIME タイプは multipart パートの Content-Type から判定されます。openai-node は fs.ReadStream をそのまま渡すと application/octet-stream として送信し、どの purpose でも拒否されるため、toFile で明示的に type を指定してください。

レスポンス

{
  "id": "file-abc123def456",
  "object": "file",
  "bytes": 482301,
  "purpose": "vision",
  "filename": "photo.png",
  "created_at": 1719450000,
  "expires_at": 1722042000
}

フィールド	型	説明
id	string	file- プレフィックス付きの安定 ID。チャット補完のコンテンツパートで使用します
object	string	常に "file"
bytes	integer	ファイルサイズ (バイト)
purpose	string	アップロード時に指定した purpose
filename	string | null	提供された場合は元のファイル名
created_at	integer	Unix タイムスタンプ
expires_at	integer | null	Unix タイムスタンプ。デフォルトはアップロードから 30 日後
page_count	integer	document アップロードでのみ存在 — PDF のページ数

チャット補完でファイルを参照する

ユーザーメッセージ内で type: "file" のコンテンツパートを使用します。クライアントが送信するのは ID のみで、バイト列が再度送信されることはありません。

{
  "model": "<vision-capable-model>",
  "messages": [{
    "role": "user",
    "content": [
      { "type": "text", "text": "What's in this image?" },
      { "type": "file", "file": { "file_id": "file-abc123def456" } }
    ]
  }]
}

Python

completion = client.chat.completions.create(
    model="<vision-capable-model>",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "What's in this image?"},
            {"type": "file", "file": {"file_id": file.id}},
        ],
    }],
)

print(completion.choices[0].message.content)

JavaScript

const completion = await client.chat.completions.create({
  model: "<vision-capable-model>",
  messages: [{
    role: "user",
    content: [
      { type: "text", text: "What's in this image?" },
      { type: "file", file: { file_id: file.id } },
    ],
  }],
});

console.log(completion.choices[0].message.content);

注意

モデルはファイルの purpose に対応する capability を持つ必要があります。purpose: "vision" には vision 対応モデル、purpose: "video" には video 対応モデル、purpose: "audio" には audio 対応モデル、purpose: "document" には vision 対応モデル (モデルは 1 ページにつき 1 枚の画像を受け取ります) が必要です。条件を満たさない場合、400 invalid_request_error が返ります。各モデルの capability は GET /v1/models を参照してください。

動画の例

{
  "model": "<video-capable-model>",
  "messages": [{
    "role": "user",
    "content": [
      { "type": "text", "text": "Describe what happens in this clip." },
      { "type": "file", "file": { "file_id": "file-vid789..." } }
    ]
  }]
}

ワイヤーフォーマットは画像と同じです — 送信するのは常に type: "file" で、ファイルの purpose がモデルへの受け渡し方を決定します。

音声の例

{
  "model": "<audio-capable-model>",
  "messages": [{
    "role": "user",
    "content": [
      { "type": "text", "text": "Transcribe and summarize this clip." },
      { "type": "file", "file": { "file_id": "file-aud456..." } }
    ]
  }]
}

シェイプは同じです。音声をアップロードせずインラインで送る場合は、OpenAI シェイプの { "type": "input_audio", "input_audio": { "data": "<base64>", "format": "wav" } } パートを直接送信することもできます。

ドキュメント (PDF) の例

{
  "model": "<vision-capable-model>",
  "messages": [{
    "role": "user",
    "content": [
      { "type": "text", "text": "Summarize this paper." },
      { "type": "file", "file": { "file_id": "file-doc456..." } }
    ]
  }]
}

ワイヤーフォーマットは同じ type: "file" 参照です。モデルは 1 ページにつき 1 枚の画像を受け取るため、vision capability が必要です。ページ数は GET /v1/files/{file_id} のレスポンスの page_count で確認できます。

PDF の処理はアップロード時に行われるため、推論レイテンシはドキュメントサイズの影響を受けません。

ファイル一覧

GET /v1/files

クエリパラメータ	型	説明
purpose	string	purpose で絞り込み
limit	integer	ページサイズ (1〜100、デフォルト 20)
after	string	カーソル: 前ページの最後のアイテムの id を指定

ファイルは新しい順 (逆時系列) で返されます。

使用例

curl "https://api.aiand.com/v1/files?purpose=vision&limit=50" \
  -H "Authorization: Bearer sk-your-api-key"

レスポンス

{
  "object": "list",
  "data": [
    { "id": "file-abc...", "object": "file", "bytes": 482301, "purpose": "vision", "filename": "photo.png", "created_at": 1719450000, "expires_at": 1722042000 }
  ],
  "has_more": false,
  "first_id": "file-abc...",
  "last_id": "file-abc..."
}

has_more: true のときは、次のリクエストの after に last_id を指定します。SDK のページネーション (client.files.list().auto_paging_iter()) は自動的に動作します。

ファイルメタデータを取得する

GET /v1/files/{file_id}

アップロードレスポンスと同じシェイプを返します。

curl https://api.aiand.com/v1/files/file-abc123 \
  -H "Authorization: Bearer sk-your-api-key"

ファイルコンテンツをダウンロードする

GET /v1/files/{file_id}/content

生のバイト列を返します。Content-Type と Content-Disposition ヘッダはアップロード時のメタデータから設定されます。

Python

content = client.files.content("file-abc123")
with open("downloaded.png", "wb") as f:
    f.write(content.read())

curl

curl https://api.aiand.com/v1/files/file-abc123/content \
  -H "Authorization: Bearer sk-your-api-key" \
  -o downloaded.png

ファイルを削除する

DELETE /v1/files/{file_id}

ファイルを削除します。以降、その ID を参照する推論リクエストは失敗します。

curl -X DELETE https://api.aiand.com/v1/files/file-abc123 \
  -H "Authorization: Bearer sk-your-api-key"

レスポンス

{
  "id": "file-abc123",
  "object": "file",
  "deleted": true
}

ファイルが存在しない、または既に削除されている場合は 404 を返します (冪等な動作)。

エラー

ステータス	error.code	発生条件
400	invalid_request_error	file/purpose の欠落、未知の purpose、許可外の mime、ファイルサイズの上限超過
400	model_capability_mismatch	チャット補完が、モデルに無い capability を必要とする purpose のファイルを参照
401	invalid_api_key	Authorization ヘッダが欠落または無効
404	file_not_found	未知の ID、または別の組織に属する ID
410	file_expired	ファイルが expires_at を過ぎている
500	server_error	内部エラー

注意事項

• ファイル ID はアップロード元の 組織 にスコープされます。組織をまたいだ参照は 404 を返します。
• 単発の小さな画像であれば、標準の {type: "image_url", image_url: {url: "data:..."}} コンテンツパートで base64 をインラインで送ることも可能です。ただしマルチターン会話や大きなアセットでは「一度アップロードしてから参照する」方式の方が効率的です。