Felo API PlatformFelo API Platform

가이드

파일 업로드

파일을 한 번 업로드한 뒤 Messages, Responses, 이미지 생성, 동영상 생성 요청에서 ID로 참조하세요.

파일을 한 번 업로드한 뒤 모델 요청에서 ID로 참조하세요. 같은 바이트를 base64로 다시 보내거나 파일을 공개 URL에 호스팅할 필요가 없습니다.

파일 ID는 Messages, Responses, 이미지 생성, 동영상 생성에서 사용할 수 있습니다. Chat Completions에서는 사용할 수 없습니다.

시작하기 전에

빠른 시작

1. 파일 업로드

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

업로드에 성공하면 HTTP 200과 파일의 메타데이터가 반환됩니다.

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

id를 저장하세요. 불투명한 문자열로 취급하고, 직접 만들거나 파싱하지 마세요.

2. 요청에서 참조

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

같은 두 단계를 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())

Node.js 20 이상에서는 다음과 같습니다.

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

업로드 규칙

  • 본문은 multipart/form-data이며 이름이 file인 파트 하나만 있어야 합니다. purpose를 포함해 다른 파트가 있으면 invalid_file로 거부됩니다.
  • Content-Type은 HTTP 클라이언트가 설정하게 하세요. 직접 설정하면 multipart boundary가 빠집니다.
  • 업로드 URL에 쿼리 파라미터를 붙이지 마세요.
  • SDK의 Files 헬퍼 대신 HTTP로 업로드하세요. OpenAI SDK의 files.create()는 항상 purpose를 보내므로 이 endpoint를 호출할 수 없습니다.
  • 시간 초과되거나 연결이 끊긴 업로드도 이미 저장되었을 수 있습니다. 다시 업로드하기 전에 파일 목록을 확인하세요.

파일 ID를 사용할 수 있는 위치

Endpoint파일 유형필요한 입력 모달리티필드
POST /api/v1/messagesPDF, 이미지file, imagemessages[].content[]
POST /api/v1/responsesPDF, 이미지file, imageinput[].content[]
POST /api/v1/images/generations이미지imageinput_references[]
POST /api/v1/videos/generations이미지imageframe_images[]
POST /api/v1/videos/generations이미지, MP4, 오디오image, video, audioinput_references[]
POST /api/v1/chat/completions지원하지 않음

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

이미지에는 {"type": "image", "source": {"type": "file", "file_id": "..."}}를 사용하세요.

Responses

파일콘텐츠 블록
PDF{"type": "input_file", "file_id": "..."}
이미지{"type": "input_image", "file_id": "...", "detail": "auto"}

file_id가 있는 블록에는 URL이나 base64 데이터를 함께 넣을 수 없습니다.

이미지 생성

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

요청의 나머지 부분, 202 응답, 폴링은 이미지 생성을 참고하세요.

동영상 생성

첫 프레임과 마지막 프레임은 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..."}
    }
  ]
}

마지막 프레임을 지정하려면 "frame_type": "last_frame" 항목을 하나 더 추가하세요. 마지막 프레임을 쓰려면 첫 프레임이 있어야 합니다.

참조 자료는 input_references에 넣습니다. 각 항목은 미디어 유형에 맞는 로케이터를 사용합니다.

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

모델이 받는 조합은 모델과 채널에 따라 다릅니다. frame_images와 input_references는 같은 요청에서 함께 사용할 수 없습니다.

로케이터 규칙

  • 이미지 및 동영상 요청에서 각 image_url, video_url, audio_url 객체에는 file_id와 url 중 정확히 하나만 있어야 하며, 다른 필드는 넣을 수 없습니다.
  • 한 배열 안에 file_id를 쓰는 항목과 url을 쓰는 항목을 섞을 수 있습니다.
  • 이미지 및 동영상 생성은 직접 업로드한 파일만 받습니다. 생성된 이미지를 다시 사용하려면 해당 출력의 url을 전달하세요.
  • 파일을 참조하는 요청은 실패해도 다른 채널로 넘어가지 않습니다. 오류를 확인하지 않고 다른 채널에서 재시도하지 마세요.
  • 파일을 참조하는 모든 작업이 종료 상태에 도달할 때까지 파일을 보관하세요. 그 전에 삭제하면 작업이 실패할 수 있습니다.

모델 지원 여부 확인

저장된 파일을 모든 모델에서 자동으로 사용할 수 있는 것은 아닙니다. 모델이 공개 카탈로그에 해당 입력 모달리티를 선언해야 합니다.

curl -s "https://openapi.felo.ai/api/platform/model-catalog/model?model=claude-haiku-4-5" \
  | jq '.data.input_modalities'
["text", "image", "file"]
보낼 항목input_modalities에 포함되어야 하는 값
PDFfile
이미지image
MP4video
오디오 파일audio

목록이 비어 있거나 없으면 해당 모델에 파일 ID가 활성화되지 않은 것입니다. 이 경우 요청은 file_model_unsupported로 실패합니다. 모델 이름으로 지원 여부를 추측하지 마세요.

제한

제한값
업로드 크기파일당 100 MiB(104,857,600바이트). 빈 파일은 거부됨
모델 요청당 참조 바이트 수합계 50,000,000바이트
모델 요청당 참조 수100
파일 이름 길이255자

같은 파일을 두 번 참조하면 두 요청 제한 모두에 두 번으로 계산됩니다. 50 MB에서 100 MiB 사이의 파일은 업로드할 수 있지만 모델 요청에서 참조할 수 없습니다. 모델이나 채널에 따라 더 낮은 제한이 적용될 수 있습니다.

파일 유형

유형은 확장자나 파트의 Content-Type이 아니라 파일 내용으로 판별합니다.

유형형식참조할 수 있는 위치
PDFPDFMessages, Responses
이미지PNG, JPEG, GIF, WebPMessages, Responses, 이미지 생성, 동영상 생성
동영상MP4동영상 생성
오디오MP3, WAV, FLAC, OGG동영상 생성
OfficeDOCX, XLSX, PPTX저장만 가능
텍스트UTF-8 텍스트. text/plain으로 저장됨저장만 가능

그 밖의 내용은 invalid_file로 거부됩니다.

파일 이름

파일 이름에는 <, >, :, ", |, ?, *, \ 및 제어 문자를 사용할 수 없습니다. /는 구분자로 사용할 수 있지만 빈 세그먼트, ., ..은 사용할 수 없습니다.

파일 관리

파일은 계정에 속합니다. 계정의 모든 API key가 같은 파일을 봅니다. 다른 계정에서는 이 파일 ID를 사용할 수 없습니다.

파일 목록 조회

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
}

결과는 오래된 순으로 정렬됩니다. has_more가 true이면 반환된 cursor를 전달해 다음 페이지를 가져오세요. 서버 측 검색이나 유형 필터는 없습니다.

파일 하나 조회

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

파일 삭제

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

삭제는 즉시 적용되며 되돌릴 수 없습니다. 503은 삭제가 완료되지 않았다는 뜻입니다. DELETE를 다시 보내세요.

다운로드

업로드한 파일은 다운로드할 수 없습니다. GET /api/v1/files/{file_id}/content는 400 file_not_downloadable을 반환하며, 업로드 응답의 Location 헤더는 파일의 바이트가 아니라 메타데이터를 가리킵니다. 업로드하는 파일은 사본을 직접 보관하세요.

생성된 미디어를 다운로드하려면 작업의 outputs에 있는 서명된 URL을 사용하세요.

API 레퍼런스

모든 endpoint는 Authorization: Bearer YOUR_API_KEY를 사용합니다. 성공 응답은 envelope 없는 일반 JSON 객체입니다.

메서드경로반환
POST/api/v1/files파일 객체
GET/api/v1/files파일 페이지
GET/api/v1/files/{file_id}파일 객체
DELETE/api/v1/files/{file_id}{"id": "...", "type": "file_deleted"}
GET/api/v1/files/{file_id}/content400 file_not_downloadable

POST, DELETE, 단일 파일 GET은 쿼리 파라미터가 하나라도 있으면 invalid_query로 거부합니다.

파일 객체

필드타입설명
idstring파일 ID. felo_file_로 시작함. file_id로 사용
typestring항상 file
sourcestring직접 업로드한 파일은 upload, 모델 출력은 generated
filenamestring업로드할 때 보낸 이름
mime_typestring내용으로 판별한 유형
size_bytesinteger바이트 단위 크기
created_atstringISO 8601 UTC 타임스탬프
downloadableboolean업로드한 파일은 false

업로드 요청

파트필수설명
file예파일. 파일 이름이 있는 multipart/form-data 파일 파트로 전송

응답에는 파일 메타데이터의 URL이 담긴 Location 헤더가 포함됩니다.

목록 파라미터

파라미터기본값설명
limit100페이지 크기. 1부터 1000까지
cursor이전 페이지의 cursor 값
after, after_idcursor의 별칭. 셋 중 하나만 전송
orderascasc만 지원
응답 필드타입설명
dataarray파일 객체. 오래된 순
first_idstring 또는 null페이지의 첫 번째 파일 ID
last_idstring 또는 null페이지의 마지막 파일 ID
cursorstring 또는 null다음 페이지를 가져올 때 cursor로 전달할 값
has_moreboolean다음 페이지가 있는지 여부

오류

Files endpoint, Responses, 이미지 및 동영상 생성은 OpenAI 오류 envelope를 사용합니다.

{
  "error": {
    "message": "This model does not accept this attachment type",
    "type": "invalid_request_error",
    "param": "frame_images.0.image_url",
    "code": "file_model_unsupported"
  }
}

Files endpoint의 오류에서는 param이 null입니다. Messages는 Anthropic 오류 형식을 반환하며 error.code가 없습니다. request ID는 X-Request-Id 응답 헤더에 있습니다.

파일 업로드 또는 관리 시 오류:

HTTPerror.code의미
400invalid_content_type본문이 multipart/form-data가 아님
400invalid_filefile 파트가 없음, 추가 파트가 있음, 빈 파일이거나 지원하지 않는 내용
400invalid_filename파일 이름이 너무 길거나 허용되지 않는 문자를 포함
413file_too_large파일이 100 MiB를 초과
400invalid_query지원하지 않는 쿼리 파라미터가 있거나 order가 asc가 아님
400invalid_limitlimit이 1부터 1000 범위를 벗어남
400invalid_cursor커서 형식이 잘못되었거나 커서를 둘 이상 보냄
400file_not_downloadable/content를 요청함
404file_not_found파일이 없거나 삭제되었거나 다른 계정의 파일
503file_storage_unavailable파일 저장소를 일시적으로 사용할 수 없음. 나중에 재시도
503file_upload_expired업로드가 제시간에 완료되지 않음. 파일을 다시 업로드

모델 요청에서 파일을 참조할 때의 오류:

HTTPerror.code의미
400invalid_file_inputID 형식이 잘못됨, 한 로케이터에 file_id와 url이 모두 있음, 또는 참조가 100개를 초과
400unsupported_file_type파일 유형이 위치와 맞지 않음. 예: 문서 블록에 MP4
400file_model_unsupported모델이 필요한 입력 모달리티를 선언하지 않음
400file_input_too_large참조한 파일의 합계가 50,000,000바이트를 초과
400file_protocol_unsupported파일 ID를 Chat Completions로 보냄
404file_not_found파일이 없거나 삭제되었거나 다른 계정의 파일이거나, 생성된 파일을 이미지 또는 동영상 생성으로 보냄

이미지 및 동영상 생성에서는 202 이후에 파일 때문에 실패할 수도 있습니다. 이 경우 작업은 failed로 끝나고 error.code에 이 코드 중 하나가 들어갑니다.

인증, 잔액, 속도 제한 오류는 오류, 속도 제한 및 재시도를 참고하세요.

관련

도움이 필요하신가요?

  • API, 결제, 계정 관련 문의는 지원에서 안내해 드립니다.
  • Discord에서 Felo 개발자와 대화해 보세요.
  • 변경 내역을 확인해 보세요.
  • 대량 구매 가격이나 구매 관련 도움이 필요하신가요? 영업팀 문의.
  • LLM으로 구축 중이신가요? llms.txt를 읽어 보세요.