# 파일 업로드

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

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

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

## 시작하기 전에

- API key. [인증](https://openapi.felo.ai/ko/docs/authentication.md)을 참고하세요.
- Base URL: `https://openapi.felo.ai`.
- 보내려는 파일 유형을 받는 모델. [모델 지원 여부 확인](#section-7)을 참고하세요.

## 빠른 시작

### 1. 파일 업로드

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

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

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

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

### 2. 요청에서 참조

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

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

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

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

### 업로드 규칙

- 본문은 `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

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

이미지에는 `{"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 데이터를 함께 넣을 수 없습니다.

### 이미지 생성

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

요청의 나머지 부분, `202` 응답, 폴링은 [이미지 생성](https://openapi.felo.ai/ko/docs/guides/image-generation.md)을 참고하세요.

### 동영상 생성

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

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

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

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

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

### 로케이터 규칙

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

## 모델 지원 여부 확인

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

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

| 보낼 항목 | `input_modalities`에 포함되어야 하는 값 |
|---|---|
| PDF | `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`이 아니라 파일 내용으로 판별합니다.

| 유형 | 형식 | 참조할 수 있는 위치 |
|---|---|---|
| PDF | PDF | 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를 사용할 수 없습니다.

### 파일 목록 조회

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

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

### 파일 하나 조회

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

### 파일 삭제

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

삭제는 즉시 적용되며 되돌릴 수 없습니다. `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` | [파일 객체](#section-16) |
| `GET` | `/api/v1/files` | [파일 페이지](#section-18) |
| `GET` | `/api/v1/files/{file_id}` | [파일 객체](#section-16) |
| `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를 사용합니다.

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

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`에 이 코드 중 하나가 들어갑니다.

인증, 잔액, 속도 제한 오류는 [오류, 속도 제한 및 재시도](https://openapi.felo.ai/ko/docs/guides/errors-and-limits.md)를 참고하세요.

## 관련

- [프로토콜 및 SDK](https://openapi.felo.ai/ko/docs/guides/protocols.md)
- [이미지 생성](https://openapi.felo.ai/ko/docs/guides/image-generation.md)
- [비동기 작업](https://openapi.felo.ai/ko/docs/guides/async-tasks.md)
- [Model API reference](https://openapi.felo.ai/ko/docs/model-api)
