アップロード

Uploads API を使うと、大きなファイル (数百 MB の動画や複数 GB のクリップ) を 5 MiB 以上 64 MiB 以下のパートに分割してアップロードできます。各パートはアップロードセッションに対して送信され、complete を呼ぶと通常の File オブジェクトに組み立てられ、推論リクエストから file_id で参照できるようになります。

OpenAI Uploads API とワイヤ互換です。公式 Python openai SDK の client.uploads.upload_file_chunked(...) ヘルパーが、一連のシーケンスを 1 回の呼び出しで実行します。相違点は 1 つ: パートは到着順に組み立てられるため、順番に 1 つずつアップロードし、同じ順序で complete してください (パートのサイズと順序を参照)。

POST /v1/uploads
POST /v1/uploads/{upload_id}/parts
POST /v1/uploads/{upload_id}/complete
POST /v1/uploads/{upload_id}/cancel

制限

制約	値
合計ファイルサイズ	8 GiB
パートあたりのサイズ	5 MiB 以上 64 MiB 以下。最後のパートを除くすべてのパートは最初のパートと同じサイズである必要があります。最後のパートはそれより小さくてもかまいません
セッションの有効期限	作成から 1 時間
許可される purpose	`video` (推奨)。`vision` も動作しますが、このサイズで使うケースはまれです

1 時間以内に完了されなかったセッションは自動的にキャンセルされます。完了したファイルは Files API の標準的な 30 日有効期限を引き継ぎます。

パートのサイズと順序

5 MiB 以上のパートサイズを 1 つ決め (SDK ヘルパーは 64 MiB を使います)、ファイルをそのサイズで分割してください。最後のパートだけは小さくてもかまいません。番号を受け取った最初のパートがセッションのパートサイズを決めます。そのバイトが保存されなくても同じです。合わない後続のパートは、期待されるサイズを示す 400 で拒否されます。サイズを変える方法はありません。キャンセルして新しいセッションを始めてください。

パートは API に到着した順に番号が付けられ、その順序で組み立てられます。パートは順番に 1 つずつアップロードし、complete には同じ順序で part_ids を渡してください。並列で送り、小さい最後のパートが先に番号を取ると、後続のパートはその 400 のままセッションを完了できません。順序が入れ替わって到着した場合、complete は誤った順序でファイルを組み立てる代わりに 400 で拒否します。指定したパートのサイズの合計は、セッション作成時に申告した bytes と正確に一致する必要があります。

クイックスタート

最も簡単なのは、Python SDK の高レベルヘルパーを使う方法です。チャンク分割はヘルパーが処理します。Node SDK には同等のヘルパーがないため、JavaScript タブでは生のエンドポイントを直接呼び出します。同じシーケンスを数行多く書くだけです。

Python
JavaScript

from pathlib import Path
from openai import OpenAI

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

upload = client.uploads.upload_file_chunked(
    file=Path("clip.mp4"),
    purpose="video",
    mime_type="video/mp4",
)

print(upload.file.id)  # → file-vid789...

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

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

const PART = 64 * 1024 * 1024;
const data = await fs.readFile("clip.mp4");

const session = await client.uploads.create({
  filename: "clip.mp4",
  purpose: "video",
  bytes: data.byteLength,
  mime_type: "video/mp4",
});

const partIds = [];
for (let offset = 0; offset < data.byteLength; offset += PART) {
  const chunk = data.subarray(offset, Math.min(offset + PART, data.byteLength));
  const part = await client.uploads.parts.create(session.id, {
    data: await toFile(chunk, "part"),
  });
  partIds.push(part.id);
}

const upload = await client.uploads.complete(session.id, { part_ids: partIds });
console.log(upload.file.id); // → file-vid789...

どちらの方法も、ファイルを均一なパートに分割し、セッションを開き、パートを順番に 1 つずつアップロードし、アップロード順の part id で complete を呼び出します。返される upload.file.id は通常の file-... ID で、他のファイルと同様にチャット補完で使用できます。

マニュアルフロー

SDK を使わない場合は、生の HTTP エンドポイントに対して同じフローを実行できます。

1. セッションを作成する

POST /v1/uploads

フィールド	型	必須	説明
`filename`	string	はい	元のファイル名
`purpose`	string	はい	`vision` または `video`
`bytes`	integer	はい	申告されたファイルの合計サイズ
`mime_type`	string	はい	MIME タイプ。purpose の許可リストに対して検証されます

curl https://api.aiand.com/v1/uploads \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "clip.mp4",
    "purpose": "video",
    "bytes": 524288000,
    "mime_type": "video/mp4"
  }'

レスポンス

{
  "id": "upload-abc123",
  "object": "upload",
  "bytes": 524288000,
  "purpose": "video",
  "filename": "clip.mp4",
  "status": "pending",
  "created_at": 1719450000,
  "expires_at": 1719453600,
  "file": null
}

2. パートをアップロードする

POST /v1/uploads/{upload_id}/parts

data フィールドを 1 つだけ含む multipart フォームでアップロードします。最後のパートを除くすべてのパートは最初のパートと同じサイズで、かつ 5 MiB 以上である必要があります。いずれのパートも 64 MiB を超えることはできません。パートは順番に 1 つずつアップロードしてください。到着順に番号が付けられ、complete にはその順序で指定する必要があります。セッションのレイアウトに合わないパートは、期待されるサイズを示す 400 で拒否されます。

curl https://api.aiand.com/v1/uploads/upload-abc123/parts \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "data=@clip.part1.bin"

レスポンス

{
  "id": "part-xyz789",
  "object": "upload.part",
  "upload_id": "upload-abc123",
  "created_at": 1719450010
}

ソースファイルのすべてのチャンクを送信し終わるまで繰り返し、各 part.id を順序付きで記録しておきます。

3. アップロードを完了する

POST /v1/uploads/{upload_id}/complete

フィールド	型	必須	説明
`part_ids`	string[]	はい	ステップ 2 で取得した `part.id` を、アップロードした順序で並べたリスト。サイズの合計は申告した `bytes` と一致する必要があります
`md5`	string	いいえ	組み立て後のファイルの MD5 (任意)

curl https://api.aiand.com/v1/uploads/upload-abc123/complete \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "part_ids": ["part-xyz789", "part-uvw456", "part-rst123"] }'

レスポンス

{
  "id": "upload-abc123",
  "object": "upload",
  "bytes": 524288000,
  "purpose": "video",
  "filename": "clip.mp4",
  "status": "completed",
  "created_at": 1719450000,
  "expires_at": 1719453600,
  "file": {
    "id": "file-vid789",
    "object": "file",
    "bytes": 524288000,
    "purpose": "video",
    "filename": "clip.mp4",
    "created_at": 1719450090,
    "expires_at": 1722042090
  }
}

file.id はチャット補完で参照可能な通常のファイル ID です。ドキュメントの場合、file には GET /v1/files/{file_id} と同様に page_count も含まれます。

complete は冪等です。成功した complete のレスポンスが失われた場合、同じセッションに対して再度呼び出すと同じ file が返ります。

4. キャンセル (任意)

POST /v1/uploads/{upload_id}/cancel

ペンディングのセッションを中止します。冪等です — 既に完了済みまたはキャンセル済みのセッションは 404 を返します。

curl -X POST https://api.aiand.com/v1/uploads/upload-abc123/cancel \
  -H "Authorization: Bearer sk-your-api-key"

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

complete が file.id を返したら、他のファイルと同じように使えます:

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

完全な例については Files → チャット補完でファイルを参照するを参照してください。

エラー

ステータス	`error.code`	発生条件
`400`	`invalid_request_error`	フィールド欠落、未知の `purpose`、許可外の mime、申告 `bytes` が purpose ごとの上限を超過、パート本文が 64 MiB 超、`part_ids` が空または他のアップロードに属する ID を含む
`400`	`invalid_request_error`	セッションに合わないパート: 最後でないのに 5 MiB 未満、最初のパートと異なるサイズ、または申告 `bytes` を超過
`400`	`invalid_request_error`	`part_ids` がアップロード順でない、同じパートを 2 回含む、またはサイズの合計が申告 `bytes` と一致しない
`400`	`invalid_request_error`	`pending` でないアップロード、または有効期限が切れたセッションへのパート追加や完了
`401`	`invalid_api_key`	`Authorization` ヘッダが欠落または無効
`404`	`not_found`	未知の `upload_id`、または別の組織に属する ID
`500`	`server_error`	内部エラー。メッセージが新しいアップロードセッションの開始を求めている場合、そのセッションは `failed` になっており再試行できません

注意事項

アップロードセッションおよび結果として生成されるファイルは、作成した組織にスコープされます。
各パートは受理された時点で永続的に保存されます。クライアントがアップロード中にクラッシュした場合は、既存の part_ids を一覧 (セッション有効期限まで保持) して続きから再開できます。
レスポンスが失われた後に再送されたパート (OpenAI SDK は接続エラーや 5xx で自動的に再送します) は、使われない 2 つ目のパートになります。組み立てたい ID だけを渡してください。重複分はセッションとともに破棄されます。
モデルはファイルの purpose に対応する capability を持つ必要があります。purpose: "video" には video 対応モデルが必要です — GET /v1/models を参照してください。