# Muat naik fail

Muat naik fail sekali, kemudian rujuk dengan ID dalam permintaan Messages, Responses, penjanaan imej dan penjanaan video.

Muat naik fail sekali, kemudian rujuk fail itu melalui ID dalam permintaan model. Ini menggantikan penghantaran semula bait yang sama sebagai base64 atau pengehosan fail di URL awam.

ID fail berfungsi dengan Messages, Responses, penjanaan imej, dan penjanaan video. Ia tidak berfungsi dengan Chat Completions.

## Sebelum anda bermula

- Kunci API. Lihat [Pengesahan](https://openapi.felo.ai/ms/docs/authentication.md).
- URL asas `https://openapi.felo.ai`.
- Model yang menerima jenis fail yang anda ingin hantar. Lihat [Semak sokongan model](#semak-sokongan-model).

## Mula pantas

### 1. Muat naik fail

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

Muat naik yang berjaya mengembalikan HTTP `200` dengan metadata fail:

```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
}
```

Simpan `id`. Anggap ia sebagai rentetan legap: jangan bina atau huraikannya sendiri.

### 2. Rujuk fail dalam permintaan

```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."}
        ]
      }
    ]
  }'
```

Dua langkah yang sama dalam 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())
```

Dan dalam Node.js 20 atau lebih baharu:

```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");
```

### Peraturan muat naik

- Badan ialah `multipart/form-data` dengan tepat satu bahagian, bernama `file`. Sebarang bahagian lain, termasuk `purpose`, ditolak dengan `invalid_file`.
- Biarkan klien HTTP anda menetapkan `Content-Type`. Menetapkannya secara manual akan menggugurkan multipart boundary.
- Jangan tambah parameter pertanyaan pada URL muat naik.
- Muat naik melalui HTTP dan bukannya melalui pembantu Files SDK. `files.create()` dalam SDK OpenAI sentiasa menghantar `purpose`, jadi ia tidak boleh memanggil endpoint ini.
- Muat naik yang tamat masa atau terputus mungkin masih telah disimpan. Senaraikan fail anda sebelum memuat naik semula.

## Tempat ID fail boleh digunakan

| Endpoint | Jenis fail | Modaliti input yang diperlukan | Medan |
|---|---|---|---|
| `POST /api/v1/messages` | PDF, imej | `file`, `image` | `messages[].content[]` |
| `POST /api/v1/responses` | PDF, imej | `file`, `image` | `input[].content[]` |
| `POST /api/v1/images/generations` | Imej | `image` | `input_references[]` |
| `POST /api/v1/videos/generations` | Imej | `image` | `frame_images[]` |
| `POST /api/v1/videos/generations` | Imej, MP4, audio | `image`, `video`, `audio` | `input_references[]` |
| `POST /api/v1/chat/completions` | Tidak disokong | | |

### 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."}
      ]
    }
  ]
}
```

Untuk imej, gunakan `{"type": "image", "source": {"type": "file", "file_id": "..."}}`.

### Responses

| Fail | Blok kandungan |
|---|---|
| PDF | `{"type": "input_file", "file_id": "..."}` |
| Imej | `{"type": "input_image", "file_id": "...", "detail": "auto"}` |

Blok yang membawa `file_id` tidak boleh turut membawa URL atau data base64.

### Penjanaan imej

```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..."}}
  ]
}
```

Bahagian permintaan yang selebihnya, respons `202`, dan tinjauan diterangkan dalam [Penjanaan Imej](https://openapi.felo.ai/ms/docs/guides/image-generation.md).

### Penjanaan video

Bingkai pertama dan terakhir diletakkan dalam `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..."}
    }
  ]
}
```

Tambah entri kedua dengan `"frame_type": "last_frame"` untuk bingkai akhir. Bingkai terakhir memerlukan bingkai pertama.

Bahan rujukan diletakkan dalam `input_references`. Setiap entri menggunakan locator yang sepadan dengan jenis medianya:

```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"}}
  ]
}
```

Gabungan yang diterima oleh sesuatu model bergantung pada model dan saluran. `frame_images` dan `input_references` tidak boleh digunakan dalam permintaan yang sama.

### Peraturan locator

- Dalam permintaan imej dan video, setiap objek `image_url`, `video_url`, atau `audio_url` mengandungi tepat satu daripada `file_id` atau `url`, dan tiada medan lain.
- Satu tatasusunan boleh mencampurkan entri yang menggunakan `file_id` dengan entri yang menggunakan `url`.
- Penjanaan imej dan video hanya menerima fail yang anda muat naik. Untuk menggunakan semula imej yang dijana, hantar `url` outputnya.
- Permintaan yang merujuk fail tidak dipindahkan ke saluran lain apabila gagal. Jangan cuba semula pada saluran lain tanpa menyemak ralatnya.
- Simpan fail sehingga setiap tugasan yang merujuknya mencapai keadaan terminal. Memadamnya lebih awal boleh menyebabkan tugasan gagal.

## Semak sokongan model

Fail yang disimpan tidak semestinya boleh digunakan dengan setiap model secara automatik. Model mesti mengisytiharkan modaliti input yang sepadan dalam katalog awam:

```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"]
```

| Untuk menghantar | `input_modalities` mesti mengandungi |
|---|---|
| PDF | `file` |
| Imej | `image` |
| MP4 | `video` |
| Fail audio | `audio` |

Senarai yang kosong atau tiada bermaksud ID fail tidak didayakan untuk model itu. Permintaan kemudiannya gagal dengan `file_model_unsupported`. Jangan buat andaian tentang sokongan berdasarkan nama model.

## Had

| Had | Nilai |
|---|---|
| Saiz muat naik | 100 MiB (104,857,600 bait) setiap fail; fail kosong ditolak |
| Bait yang dirujuk setiap permintaan model | 50,000,000 bait secara keseluruhan |
| Rujukan setiap permintaan model | 100 |
| Panjang nama fail | 255 aksara |

Merujuk fail yang sama dua kali dikira dua kali terhadap kedua-dua had permintaan. Fail antara 50 MB dan 100 MiB boleh dimuat naik tetapi tidak boleh dirujuk dalam permintaan model. Model atau saluran boleh mengenakan had yang lebih rendah.

### Jenis fail

Jenis dikesan daripada kandungan fail, bukan daripada sambungannya atau `Content-Type` bahagian itu.

| Jenis | Format | Boleh dirujuk dalam |
|---|---|---|
| PDF | PDF | Messages, Responses |
| Imej | PNG, JPEG, GIF, WebP | Messages, Responses, penjanaan imej, penjanaan video |
| Video | MP4 | Penjanaan video |
| Audio | MP3, WAV, FLAC, OGG | Penjanaan video |
| Office | DOCX, XLSX, PPTX | Storan sahaja |
| Teks | Teks UTF-8, disimpan sebagai `text/plain` | Storan sahaja |

Sebarang kandungan lain ditolak dengan `invalid_file`.

### Nama fail

Nama fail tidak boleh mengandungi `<`, `>`, `:`, `"`, `|`, `?`, `*`, `\`, atau aksara kawalan. `/` dibenarkan sebagai pemisah, tetapi segmen kosong, `.`, dan `..` tidak dibenarkan.

## Urus fail

Fail adalah milik akaun anda. Setiap kunci API dalam akaun melihat fail yang sama; akaun lain tidak boleh menggunakan ID fail anda.

### Senaraikan fail

```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
}
```

Hasil disusun bermula daripada yang paling lama. Apabila `has_more` ialah `true`, hantar `cursor` yang dikembalikan untuk mendapatkan halaman seterusnya. Tiada carian atau penapis jenis di sisi pelayan.

### Dapatkan satu fail

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

### Padam fail

```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"}
```

Pemadaman berkuat kuasa serta-merta dan tidak boleh dibuat asal. `503` bermaksud pemadaman tidak selesai; hantar `DELETE` sekali lagi.

### Muat turun

Fail yang dimuat naik tidak boleh dimuat turun. `GET /api/v1/files/{file_id}/content` mengembalikan `400 file_not_downloadable`, dan pengepala `Location` pada respons muat naik menunjuk ke metadata fail, bukan baitnya. Simpan salinan anda sendiri bagi apa-apa yang anda muat naik.

Untuk memuat turun media yang dijana, gunakan URL bertandatangan dalam `outputs` tugasan.

## Rujukan API

Semua endpoint menggunakan `Authorization: Bearer YOUR_API_KEY`. Respons yang berjaya ialah objek JSON biasa tanpa sampul.

| Kaedah | Laluan | Mengembalikan |
|---|---|---|
| `POST` | `/api/v1/files` | [Objek fail](#objek-fail) |
| `GET` | `/api/v1/files` | [Satu halaman fail](#parameter-senarai) |
| `GET` | `/api/v1/files/{file_id}` | [Objek fail](#objek-fail) |
| `DELETE` | `/api/v1/files/{file_id}` | `{"id": "...", "type": "file_deleted"}` |
| `GET` | `/api/v1/files/{file_id}/content` | `400 file_not_downloadable` |

`POST`, `DELETE`, dan `GET` untuk satu fail menolak sebarang parameter pertanyaan dengan `invalid_query`.

### Objek fail

| Medan | Jenis | Penerangan |
|---|---|---|
| `id` | string | ID fail, berawalan `felo_file_`. Gunakannya sebagai `file_id` |
| `type` | string | Sentiasa `file` |
| `source` | string | `upload` untuk fail yang anda muat naik, `generated` untuk output model |
| `filename` | string | Nama yang dihantar bersama muat naik |
| `mime_type` | string | Jenis yang dikesan daripada kandungan |
| `size_bytes` | integer | Saiz dalam bait |
| `created_at` | string | Cap masa UTC ISO 8601 |
| `downloadable` | boolean | `false` untuk fail yang dimuat naik |

### Permintaan muat naik

| Bahagian | Diperlukan | Penerangan |
|---|---|---|
| `file` | Ya | Fail itu, dihantar sebagai bahagian fail `multipart/form-data` dengan nama fail |

Respons menyertakan pengepala `Location` dengan URL metadata fail.

### Parameter senarai

| Parameter | Lalai | Penerangan |
|---|---|---|
| `limit` | `100` | Saiz halaman, dari 1 hingga 1000 |
| `cursor` | | Nilai `cursor` daripada halaman sebelumnya |
| `after`, `after_id` | | Alias bagi `cursor`. Hantar satu sahaja daripada ketiga-tiganya |
| `order` | `asc` | Hanya `asc` disokong |

| Medan respons | Jenis | Penerangan |
|---|---|---|
| `data` | array | Objek fail, bermula daripada yang paling lama |
| `first_id` | string atau null | ID fail pertama pada halaman |
| `last_id` | string atau null | ID fail terakhir pada halaman |
| `cursor` | string atau null | Nilai untuk dihantar sebagai `cursor` bagi halaman seterusnya |
| `has_more` | boolean | Sama ada halaman lain wujud |

## Ralat

Endpoint Files, Responses, serta penjanaan imej dan video menggunakan sampul ralat 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"
  }
}
```

`param` ialah `null` untuk ralat daripada endpoint Files. Messages mengembalikan bentuk ralat Anthropic, yang tidak mempunyai `error.code`. ID permintaan berada dalam pengepala respons `X-Request-Id`.

Ralat semasa memuat naik atau mengurus fail:

| HTTP | `error.code` | Maksud |
|---|---|---|
| 400 | `invalid_content_type` | Badan bukan `multipart/form-data` |
| 400 | `invalid_file` | Tiada bahagian `file`, ada bahagian tambahan, fail kosong, atau kandungan tidak disokong |
| 400 | `invalid_filename` | Nama fail terlalu panjang atau mengandungi aksara yang ditolak |
| 413 | `file_too_large` | Fail melebihi 100 MiB |
| 400 | `invalid_query` | Parameter pertanyaan yang tidak disokong, atau `order` selain `asc` |
| 400 | `invalid_limit` | `limit` di luar julat 1 hingga 1000 |
| 400 | `invalid_cursor` | Format kursor tidak betul, atau lebih daripada satu kursor dihantar |
| 400 | `file_not_downloadable` | `/content` diminta |
| 404 | `file_not_found` | Fail tidak wujud, telah dipadam, atau milik akaun lain |
| 503 | `file_storage_unavailable` | Storan fail tidak tersedia buat sementara waktu; cuba semula kemudian |
| 503 | `file_upload_expired` | Muat naik tidak selesai dalam masa yang ditetapkan; muat naik fail sekali lagi |

Ralat semasa merujuk fail dalam permintaan model:

| HTTP | `error.code` | Maksud |
|---|---|---|
| 400 | `invalid_file_input` | Format ID tidak betul, `file_id` dan `url` kedua-duanya dalam satu locator, atau lebih daripada 100 rujukan |
| 400 | `unsupported_file_type` | Jenis fail tidak sepadan dengan kedudukannya, contohnya MP4 dalam blok dokumen |
| 400 | `file_model_unsupported` | Model tidak mengisytiharkan modaliti input yang diperlukan |
| 400 | `file_input_too_large` | Fail yang dirujuk melebihi 50,000,000 bait secara keseluruhan |
| 400 | `file_protocol_unsupported` | ID fail dihantar ke Chat Completions |
| 404 | `file_not_found` | Fail tiada, telah dipadam, dimiliki akaun lain, atau merupakan fail dijana yang dihantar ke penjanaan imej atau video |

Bagi penjanaan imej dan video, fail juga boleh gagal selepas `202`. Tugasan kemudiannya berakhir sebagai `failed` dengan salah satu kod ini dalam `error.code`.

Ralat pengesahan, baki, dan had kadar diterangkan dalam [Ralat, Had, dan Cuba Semula](https://openapi.felo.ai/ms/docs/guides/errors-and-limits.md).

## Berkaitan

- [Protokol dan SDK](https://openapi.felo.ai/ms/docs/guides/protocols.md)
- [Penjanaan Imej](https://openapi.felo.ai/ms/docs/guides/image-generation.md)
- [Tugasan Tak Segerak](https://openapi.felo.ai/ms/docs/guides/async-tasks.md)
- [Rujukan API Model](https://openapi.felo.ai/ms/docs/model-api)
