가이드
파일 업로드
파일을 한 번 업로드한 뒤 Messages, Responses, 이미지 생성, 동영상 생성 요청에서 ID로 참조하세요.
파일을 한 번 업로드한 뒤 모델 요청에서 ID로 참조하세요. 같은 바이트를 base64로 다시 보내거나 파일을 공개 URL에 호스팅할 필요가 없습니다.
파일 ID는 Messages, Responses, 이미지 생성, 동영상 생성에서 사용할 수 있습니다. Chat Completions에서는 사용할 수 없습니다.
시작하기 전에
- API key. 인증을 참고하세요.
- Base URL:
https://openapi.felo.ai. - 보내려는 파일 유형을 받는 모델. 모델 지원 여부 확인을 참고하세요.
빠른 시작
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/messages | PDF, 이미지 | file, image | messages[].content[] |
POST /api/v1/responses | PDF, 이미지 | file, image | input[].content[] |
POST /api/v1/images/generations | 이미지 | image | input_references[] |
POST /api/v1/videos/generations | 이미지 | image | frame_images[] |
POST /api/v1/videos/generations | 이미지, MP4, 오디오 | image, video, audio | input_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
| 파일 | 콘텐츠 블록 |
|---|---|
{"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에 포함되어야 하는 값 |
|---|---|
file | |
| 이미지 | image |
| MP4 | video |
| 오디오 파일 | audio |
목록이 비어 있거나 없으면 해당 모델에 파일 ID가 활성화되지 않은 것입니다. 이 경우 요청은 file_model_unsupported로 실패합니다. 모델 이름으로 지원 여부를 추측하지 마세요.
제한
| 제한 | 값 |
|---|---|
| 업로드 크기 | 파일당 100 MiB(104,857,600바이트). 빈 파일은 거부됨 |
| 모델 요청당 참조 바이트 수 | 합계 50,000,000바이트 |
| 모델 요청당 참조 수 | 100 |
| 파일 이름 길이 | 255자 |
같은 파일을 두 번 참조하면 두 요청 제한 모두에 두 번으로 계산됩니다. 50 MB에서 100 MiB 사이의 파일은 업로드할 수 있지만 모델 요청에서 참조할 수 없습니다. 모델이나 채널에 따라 더 낮은 제한이 적용될 수 있습니다.
파일 유형
유형은 확장자나 파트의 Content-Type이 아니라 파일 내용으로 판별합니다.
| 유형 | 형식 | 참조할 수 있는 위치 |
|---|---|---|
| Messages, Responses | ||
| 이미지 | PNG, JPEG, GIF, WebP | Messages, Responses, 이미지 생성, 동영상 생성 |
| 동영상 | MP4 | 동영상 생성 |
| 오디오 | MP3, WAV, FLAC, OGG | 동영상 생성 |
| Office | DOCX, 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}/content | 400 file_not_downloadable |
POST, DELETE, 단일 파일 GET은 쿼리 파라미터가 하나라도 있으면 invalid_query로 거부합니다.
파일 객체
| 필드 | 타입 | 설명 |
|---|---|---|
id | string | 파일 ID. felo_file_로 시작함. file_id로 사용 |
type | string | 항상 file |
source | string | 직접 업로드한 파일은 upload, 모델 출력은 generated |
filename | string | 업로드할 때 보낸 이름 |
mime_type | string | 내용으로 판별한 유형 |
size_bytes | integer | 바이트 단위 크기 |
created_at | string | ISO 8601 UTC 타임스탬프 |
downloadable | boolean | 업로드한 파일은 false |
업로드 요청
| 파트 | 필수 | 설명 |
|---|---|---|
file | 예 | 파일. 파일 이름이 있는 multipart/form-data 파일 파트로 전송 |
응답에는 파일 메타데이터의 URL이 담긴 Location 헤더가 포함됩니다.
목록 파라미터
| 파라미터 | 기본값 | 설명 |
|---|---|---|
limit | 100 | 페이지 크기. 1부터 1000까지 |
cursor | 이전 페이지의 cursor 값 | |
after, after_id | cursor의 별칭. 셋 중 하나만 전송 | |
order | asc | asc만 지원 |
| 응답 필드 | 타입 | 설명 |
|---|---|---|
data | array | 파일 객체. 오래된 순 |
first_id | string 또는 null | 페이지의 첫 번째 파일 ID |
last_id | string 또는 null | 페이지의 마지막 파일 ID |
cursor | string 또는 null | 다음 페이지를 가져올 때 cursor로 전달할 값 |
has_more | boolean | 다음 페이지가 있는지 여부 |
오류
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 응답 헤더에 있습니다.
파일 업로드 또는 관리 시 오류:
| HTTP | error.code | 의미 |
|---|---|---|
| 400 | invalid_content_type | 본문이 multipart/form-data가 아님 |
| 400 | invalid_file | file 파트가 없음, 추가 파트가 있음, 빈 파일이거나 지원하지 않는 내용 |
| 400 | invalid_filename | 파일 이름이 너무 길거나 허용되지 않는 문자를 포함 |
| 413 | file_too_large | 파일이 100 MiB를 초과 |
| 400 | invalid_query | 지원하지 않는 쿼리 파라미터가 있거나 order가 asc가 아님 |
| 400 | invalid_limit | limit이 1부터 1000 범위를 벗어남 |
| 400 | invalid_cursor | 커서 형식이 잘못되었거나 커서를 둘 이상 보냄 |
| 400 | file_not_downloadable | /content를 요청함 |
| 404 | file_not_found | 파일이 없거나 삭제되었거나 다른 계정의 파일 |
| 503 | file_storage_unavailable | 파일 저장소를 일시적으로 사용할 수 없음. 나중에 재시도 |
| 503 | file_upload_expired | 업로드가 제시간에 완료되지 않음. 파일을 다시 업로드 |
모델 요청에서 파일을 참조할 때의 오류:
| HTTP | error.code | 의미 |
|---|---|---|
| 400 | invalid_file_input | ID 형식이 잘못됨, 한 로케이터에 file_id와 url이 모두 있음, 또는 참조가 100개를 초과 |
| 400 | unsupported_file_type | 파일 유형이 위치와 맞지 않음. 예: 문서 블록에 MP4 |
| 400 | file_model_unsupported | 모델이 필요한 입력 모달리티를 선언하지 않음 |
| 400 | file_input_too_large | 참조한 파일의 합계가 50,000,000바이트를 초과 |
| 400 | file_protocol_unsupported | 파일 ID를 Chat Completions로 보냄 |
| 404 | file_not_found | 파일이 없거나 삭제되었거나 다른 계정의 파일이거나, 생성된 파일을 이미지 또는 동영상 생성으로 보냄 |
이미지 및 동영상 생성에서는 202 이후에 파일 때문에 실패할 수도 있습니다. 이 경우 작업은 failed로 끝나고 error.code에 이 코드 중 하나가 들어갑니다.
인증, 잔액, 속도 제한 오류는 오류, 속도 제한 및 재시도를 참고하세요.