# Unggah file

Unggah file sekali, lalu rujuk dengan ID dalam permintaan Messages, Responses, pembuatan gambar, dan pembuatan video.

Unggah file satu kali, lalu rujuk file itu dengan ID-nya dalam permintaan model. Cara ini menggantikan pengiriman ulang byte yang sama sebagai base64 atau hosting file di URL publik.

ID file dapat digunakan dengan Messages, Responses, generasi gambar, dan generasi video. ID file tidak dapat digunakan dengan Chat Completions.

## Sebelum Anda memulai

- Kunci API. Lihat [Autentikasi](https://openapi.felo.ai/id/docs/authentication.md).
- Base URL `https://openapi.felo.ai`.
- Model yang menerima jenis file yang akan Anda kirim. Lihat [Periksa dukungan model](#periksa-dukungan-model).

## Mulai cepat

### 1. Unggah file

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

Unggahan yang berhasil mengembalikan HTTP `200` beserta metadata file:

```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`. Perlakukan sebagai string opak: jangan menyusunnya sendiri atau mengurainya.

### 2. Rujuk file 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 yang lebih baru:

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

### Aturan unggah

- Body berupa `multipart/form-data` dengan tepat satu bagian, bernama `file`. Bagian lain apa pun, termasuk `purpose`, ditolak dengan `invalid_file`.
- Biarkan klien HTTP Anda yang menetapkan `Content-Type`. Menetapkannya secara manual akan menghilangkan multipart boundary.
- Jangan menambahkan parameter kueri ke URL unggah.
- Unggah melalui HTTP, bukan melalui helper Files milik SDK. `files.create()` pada OpenAI SDK selalu mengirim `purpose`, sehingga tidak dapat memanggil endpoint ini.
- Unggahan yang kehabisan waktu atau terputus mungkin tetap tersimpan. Tampilkan daftar file Anda sebelum mengunggah lagi.

## Di mana ID file dapat digunakan

| Endpoint | Jenis file | Modalitas input yang diperlukan | Field |
|---|---|---|---|
| `POST /api/v1/messages` | PDF, gambar | `file`, `image` | `messages[].content[]` |
| `POST /api/v1/responses` | PDF, gambar | `file`, `image` | `input[].content[]` |
| `POST /api/v1/images/generations` | Gambar | `image` | `input_references[]` |
| `POST /api/v1/videos/generations` | Gambar | `image` | `frame_images[]` |
| `POST /api/v1/videos/generations` | Gambar, MP4, audio | `image`, `video`, `audio` | `input_references[]` |
| `POST /api/v1/chat/completions` | Tidak didukung | | |

### 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 gambar, gunakan `{"type": "image", "source": {"type": "file", "file_id": "..."}}`.

### Responses

| File | Blok konten |
|---|---|
| PDF | `{"type": "input_file", "file_id": "..."}` |
| Gambar | `{"type": "input_image", "file_id": "...", "detail": "auto"}` |

Blok yang memuat `file_id` tidak boleh sekaligus memuat URL atau data base64.

### Generasi gambar

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

Bagian lain dari permintaan, respons `202`, dan polling dijelaskan di [Generasi Gambar](https://openapi.felo.ai/id/docs/guides/image-generation.md).

### Generasi video

Frame pertama dan terakhir ditempatkan di `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..."}
    }
  ]
}
```

Tambahkan entri kedua dengan `"frame_type": "last_frame"` untuk frame akhir. Frame terakhir memerlukan frame pertama.

Materi referensi ditempatkan di `input_references`. Setiap entri menggunakan locator yang sesuai 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"}}
  ]
}
```

Kombinasi mana yang diterima sebuah model bergantung pada model dan kanalnya. `frame_images` dan `input_references` tidak dapat digunakan dalam permintaan yang sama.

### Aturan locator

- Dalam permintaan gambar dan video, setiap objek `image_url`, `video_url`, atau `audio_url` berisi tepat satu dari `file_id` atau `url`, dan tidak ada field lain.
- Satu array dapat mencampur entri yang menggunakan `file_id` dengan entri yang menggunakan `url`.
- Generasi gambar dan video hanya menerima file yang Anda unggah. Untuk menggunakan kembali gambar yang dihasilkan, kirim `url` output-nya.
- Permintaan yang merujuk file tidak dipindahkan ke kanal lain saat gagal. Jangan mencobanya ulang di kanal lain tanpa memeriksa error-nya.
- Simpan file hingga setiap tugas yang merujuknya mencapai status terminal. Menghapusnya lebih awal dapat menggagalkan tugas.

## Periksa dukungan model

File yang tersimpan tidak otomatis dapat digunakan dengan setiap model. Model harus mendeklarasikan modalitas input yang sesuai di katalog publik:

```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 mengirim | `input_modalities` harus menyertakan |
|---|---|
| PDF | `file` |
| Gambar | `image` |
| MP4 | `video` |
| File audio | `audio` |

Daftar yang kosong atau tidak ada berarti ID file tidak diaktifkan untuk model tersebut. Permintaan kemudian gagal dengan `file_model_unsupported`. Jangan menyimpulkan dukungan dari nama model.

## Batas

| Batas | Nilai |
|---|---|
| Ukuran unggahan | 100 MiB (104,857,600 byte) per file; file kosong ditolak |
| Byte yang dirujuk per permintaan model | Total 50,000,000 byte |
| Referensi per permintaan model | 100 |
| Panjang nama file | 255 karakter |

Merujuk file yang sama dua kali dihitung dua kali terhadap kedua batas permintaan. File berukuran antara 50 MB dan 100 MiB dapat diunggah tetapi tidak dapat dirujuk dalam permintaan model. Model atau kanal dapat menerapkan batas yang lebih rendah.

### Jenis file

Jenis dideteksi dari konten file, bukan dari ekstensinya atau `Content-Type` bagian tersebut.

| Jenis | Format | Dapat dirujuk di |
|---|---|---|
| PDF | PDF | Messages, Responses |
| Gambar | PNG, JPEG, GIF, WebP | Messages, Responses, generasi gambar, generasi video |
| Video | MP4 | Generasi video |
| Audio | MP3, WAV, FLAC, OGG | Generasi video |
| Office | DOCX, XLSX, PPTX | Hanya penyimpanan |
| Teks | Teks UTF-8, disimpan sebagai `text/plain` | Hanya penyimpanan |

Konten lain apa pun ditolak dengan `invalid_file`.

### Nama file

Nama file tidak boleh berisi `<`, `>`, `:`, `"`, `|`, `?`, `*`, `\`, atau karakter kontrol. `/` diperbolehkan sebagai pemisah, tetapi segmen kosong, `.`, dan `..` tidak.

## Mengelola file

File adalah milik akun Anda. Setiap kunci API pada akun melihat file yang sama; akun lain tidak dapat menggunakan ID file Anda.

### Menampilkan daftar file

```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 diurutkan dari yang terlama. Jika `has_more` bernilai `true`, kirim `cursor` yang dikembalikan untuk mendapatkan halaman berikutnya. Tidak ada pencarian atau filter jenis di sisi server.

### Mengambil satu file

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

### Menghapus file

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

Penghapusan langsung berlaku dan tidak dapat dibatalkan. `503` berarti penghapusan tidak selesai; kirim `DELETE` lagi.

### Unduhan

File yang diunggah tidak dapat diunduh. `GET /api/v1/files/{file_id}/content` mengembalikan `400 file_not_downloadable`, dan header `Location` pada respons unggah menunjuk ke metadata file, bukan byte-nya. Simpan salinan Anda sendiri untuk apa pun yang Anda unggah.

Untuk mengunduh media yang dihasilkan, gunakan URL bertanda tangan di `outputs` tugas.

## Referensi API

Semua endpoint menggunakan `Authorization: Bearer YOUR_API_KEY`. Respons yang berhasil berupa objek JSON biasa tanpa envelope.

| Metode | Path | Mengembalikan |
|---|---|---|
| `POST` | `/api/v1/files` | [Objek file](#objek-file) |
| `GET` | `/api/v1/files` | [Satu halaman file](#parameter-daftar) |
| `GET` | `/api/v1/files/{file_id}` | [Objek file](#objek-file) |
| `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 file menolak parameter kueri apa pun dengan `invalid_query`.

### Objek file

| Field | Tipe | Deskripsi |
|---|---|---|
| `id` | string | ID file, berawalan `felo_file_`. Gunakan sebagai `file_id` |
| `type` | string | Selalu `file` |
| `source` | string | `upload` untuk file yang Anda unggah, `generated` untuk output model |
| `filename` | string | Nama yang dikirim bersama unggahan |
| `mime_type` | string | Jenis yang dideteksi dari konten |
| `size_bytes` | integer | Ukuran dalam byte |
| `created_at` | string | Stempel waktu UTC ISO 8601 |
| `downloadable` | boolean | `false` untuk file yang diunggah |

### Permintaan unggah

| Bagian | Wajib | Deskripsi |
|---|---|---|
| `file` | Ya | File, dikirim sebagai bagian file `multipart/form-data` dengan nama file |

Respons menyertakan header `Location` berisi URL metadata file.

### Parameter daftar

| Parameter | Default | Deskripsi |
|---|---|---|
| `limit` | `100` | Ukuran halaman, dari 1 hingga 1000 |
| `cursor` | | Nilai `cursor` dari halaman sebelumnya |
| `after`, `after_id` | | Alias dari `cursor`. Kirim hanya satu dari ketiganya |
| `order` | `asc` | Hanya `asc` yang didukung |

| Field respons | Tipe | Deskripsi |
|---|---|---|
| `data` | array | Objek file, dari yang terlama |
| `first_id` | string atau null | ID file pertama pada halaman |
| `last_id` | string atau null | ID file terakhir pada halaman |
| `cursor` | string atau null | Nilai yang dikirim sebagai `cursor` untuk halaman berikutnya |
| `has_more` | boolean | Apakah ada halaman lain |

## Error

Endpoint Files, Responses, serta generasi gambar dan video menggunakan envelope error 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` bernilai `null` untuk error dari endpoint Files. Messages mengembalikan bentuk error Anthropic, yang tidak memiliki `error.code`. ID permintaan berada di header respons `X-Request-Id`.

Error saat mengunggah atau mengelola file:

| HTTP | `error.code` | Arti |
|---|---|---|
| 400 | `invalid_content_type` | Body bukan `multipart/form-data` |
| 400 | `invalid_file` | Tidak ada bagian `file`, ada bagian tambahan, file kosong, atau konten tidak didukung |
| 400 | `invalid_filename` | Nama file terlalu panjang atau berisi karakter yang ditolak |
| 413 | `file_too_large` | File melebihi 100 MiB |
| 400 | `invalid_query` | Parameter kueri yang tidak didukung, atau `order` selain `asc` |
| 400 | `invalid_limit` | `limit` di luar rentang 1 hingga 1000 |
| 400 | `invalid_cursor` | Cursor salah format, atau lebih dari satu cursor dikirim |
| 400 | `file_not_downloadable` | `/content` diminta |
| 404 | `file_not_found` | File tidak ada, telah dihapus, atau milik akun lain |
| 503 | `file_storage_unavailable` | Penyimpanan file sementara tidak tersedia; coba lagi nanti |
| 503 | `file_upload_expired` | Unggahan tidak selesai tepat waktu; unggah file lagi |

Error saat merujuk file dalam permintaan model:

| HTTP | `error.code` | Arti |
|---|---|---|
| 400 | `invalid_file_input` | ID salah format, `file_id` dan `url` sekaligus dalam satu locator, atau lebih dari 100 referensi |
| 400 | `unsupported_file_type` | Jenis file tidak sesuai dengan posisinya, misalnya MP4 di blok dokumen |
| 400 | `file_model_unsupported` | Model tidak mendeklarasikan modalitas input yang diperlukan |
| 400 | `file_input_too_large` | File yang dirujuk melebihi total 50,000,000 byte |
| 400 | `file_protocol_unsupported` | ID file dikirim ke Chat Completions |
| 404 | `file_not_found` | File tidak ada, telah dihapus, dimiliki akun lain, atau merupakan file hasil generasi yang dikirim ke generasi gambar atau video |

Untuk generasi gambar dan video, file juga dapat gagal setelah `202`. Tugas kemudian berakhir sebagai `failed` dengan salah satu kode ini di `error.code`.

Error autentikasi, saldo, dan batas laju dijelaskan di [Error, Batas, dan Percobaan Ulang](https://openapi.felo.ai/id/docs/guides/errors-and-limits.md).

## Terkait

- [Protokol dan SDK](https://openapi.felo.ai/id/docs/guides/protocols.md)
- [Generasi Gambar](https://openapi.felo.ai/id/docs/guides/image-generation.md)
- [Tugas Asinkron](https://openapi.felo.ai/id/docs/guides/async-tasks.md)
- [Referensi Model API](https://openapi.felo.ai/id/docs/model-api)
