Felo API PlatformFelo API Platform

Panduan

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

Mula pantas

1. Muat naik fail

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:

{
  "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

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:

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:

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

EndpointJenis failModaliti input yang diperlukanMedan
POST /api/v1/messagesPDF, imejfile, imagemessages[].content[]
POST /api/v1/responsesPDF, imejfile, imageinput[].content[]
POST /api/v1/images/generationsImejimageinput_references[]
POST /api/v1/videos/generationsImejimageframe_images[]
POST /api/v1/videos/generationsImej, MP4, audioimage, video, audioinput_references[]
POST /api/v1/chat/completionsTidak disokong

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

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

Responses

FailBlok 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

{
  "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.

Penjanaan video

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

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:

{
  "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:

curl -s "https://openapi.felo.ai/api/platform/model-catalog/model?model=claude-haiku-4-5" \
  | jq '.data.input_modalities'
["text", "image", "file"]
Untuk menghantarinput_modalities mesti mengandungi
PDFfile
Imejimage
MP4video
Fail audioaudio

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

HadNilai
Saiz muat naik100 MiB (104,857,600 bait) setiap fail; fail kosong ditolak
Bait yang dirujuk setiap permintaan model50,000,000 bait secara keseluruhan
Rujukan setiap permintaan model100
Panjang nama fail255 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.

JenisFormatBoleh dirujuk dalam
PDFPDFMessages, Responses
ImejPNG, JPEG, GIF, WebPMessages, Responses, penjanaan imej, penjanaan video
VideoMP4Penjanaan video
AudioMP3, WAV, FLAC, OGGPenjanaan video
OfficeDOCX, XLSX, PPTXStoran sahaja
TeksTeks UTF-8, disimpan sebagai text/plainStoran 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

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
}

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

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

Padam fail

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

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.

KaedahLaluanMengembalikan
POST/api/v1/filesObjek fail
GET/api/v1/filesSatu halaman fail
GET/api/v1/files/{file_id}Objek fail
DELETE/api/v1/files/{file_id}{"id": "...", "type": "file_deleted"}
GET/api/v1/files/{file_id}/content400 file_not_downloadable

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

Objek fail

MedanJenisPenerangan
idstringID fail, berawalan felo_file_. Gunakannya sebagai file_id
typestringSentiasa file
sourcestringupload untuk fail yang anda muat naik, generated untuk output model
filenamestringNama yang dihantar bersama muat naik
mime_typestringJenis yang dikesan daripada kandungan
size_bytesintegerSaiz dalam bait
created_atstringCap masa UTC ISO 8601
downloadablebooleanfalse untuk fail yang dimuat naik

Permintaan muat naik

BahagianDiperlukanPenerangan
fileYaFail itu, dihantar sebagai bahagian fail multipart/form-data dengan nama fail

Respons menyertakan pengepala Location dengan URL metadata fail.

Parameter senarai

ParameterLalaiPenerangan
limit100Saiz halaman, dari 1 hingga 1000
cursorNilai cursor daripada halaman sebelumnya
after, after_idAlias bagi cursor. Hantar satu sahaja daripada ketiga-tiganya
orderascHanya asc disokong
Medan responsJenisPenerangan
dataarrayObjek fail, bermula daripada yang paling lama
first_idstring atau nullID fail pertama pada halaman
last_idstring atau nullID fail terakhir pada halaman
cursorstring atau nullNilai untuk dihantar sebagai cursor bagi halaman seterusnya
has_morebooleanSama ada halaman lain wujud

Ralat

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

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:

HTTPerror.codeMaksud
400invalid_content_typeBadan bukan multipart/form-data
400invalid_fileTiada bahagian file, ada bahagian tambahan, fail kosong, atau kandungan tidak disokong
400invalid_filenameNama fail terlalu panjang atau mengandungi aksara yang ditolak
413file_too_largeFail melebihi 100 MiB
400invalid_queryParameter pertanyaan yang tidak disokong, atau order selain asc
400invalid_limitlimit di luar julat 1 hingga 1000
400invalid_cursorFormat kursor tidak betul, atau lebih daripada satu kursor dihantar
400file_not_downloadable/content diminta
404file_not_foundFail tidak wujud, telah dipadam, atau milik akaun lain
503file_storage_unavailableStoran fail tidak tersedia buat sementara waktu; cuba semula kemudian
503file_upload_expiredMuat naik tidak selesai dalam masa yang ditetapkan; muat naik fail sekali lagi

Ralat semasa merujuk fail dalam permintaan model:

HTTPerror.codeMaksud
400invalid_file_inputFormat ID tidak betul, file_id dan url kedua-duanya dalam satu locator, atau lebih daripada 100 rujukan
400unsupported_file_typeJenis fail tidak sepadan dengan kedudukannya, contohnya MP4 dalam blok dokumen
400file_model_unsupportedModel tidak mengisytiharkan modaliti input yang diperlukan
400file_input_too_largeFail yang dirujuk melebihi 50,000,000 bait secara keseluruhan
400file_protocol_unsupportedID fail dihantar ke Chat Completions
404file_not_foundFail 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.

Berkaitan

Perlukan bantuan?