# 파일

입력 파일을 업로드하고 결과 파일을 다운로드합니다.

출처: https://scifig.ai/ko/docs/api/files

## 업로드

`POST /files`는 `multipart/form-data`를 받으며 `figures:generate` 범위가 필요합니다. `201`과 함께 `file_id`, `purpose`, `content_type`, `size_bytes`, `expires_at`, `created_at`을 반환합니다.

| 필드 | 유형 | 필수 | 기본값 | 규칙 |
| --- | --- | --- | --- | --- |
| file | file | 예 | — | 아래 용도별 제한 참조 |
| purpose | string | 아니요 | `image` | `image`, `mask` 또는 `flowchart_attachment` |

| 용도 | 지원 형식 | 사용처 |
| --- | --- | --- |
| image | 최대 20 MB의 PNG, JPEG 또는 WebP(파일명이 아닌 내용으로 검증) | 편집, 텍스트 감지, 업스케일, 변환, 참조 이미지 |
| mask | 최대 8 MB의 PNG. 흰색은 다시 그릴 영역을 표시 | `POST /images/edits` |
| flowchart_attachment | FlowChart 작업 공간에서 지원하는 형식, 최대 32 MB | `POST /flowcharts/generations` |

업로드한 파일은 24시간 동안 사용할 수 있습니다. 이후에는 `file_id`를 찾을 수 없습니다(`400 INVALID_REQUEST`, `FILE_NOT_FOUND`). 입력 용도로만 사용되므로 작업 응답에 나타나지 않으며 누구와도 공유되지 않습니다.

업로드에는 웹사이트와 같은 한도가 적용됩니다. 초과하면 `Retry-After`와 `details.reason`을 포함한 `429 RATE_LIMITED`를 반환합니다. 분당 한도는 `UPLOAD_RATE_LIMITED`, 순서도 첨부 파일의 일일 한도는 `UPLOAD_DAILY_LIMIT_REACHED`로 표시합니다.

업로드에는 `Idempotency-Key` 헤더를 선택적으로 지정할 수 있습니다(출력 가능한 ASCII 문자 1–255자). 같은 계정, 키, `purpose`는 항상 하나의 `file_id`에 대응합니다. 다시 보내면 업로드하거나 업로드 한도를 소모하지 않고 첫 파일을 `201`로 반환합니다. 같은 키와 `purpose`에 다른 바이트를 보내면 `409 IDEMPOTENCY_CONFLICT`를 반환합니다. 헤더가 없으면 매번 새 파일을 만듭니다. 해당 업로드가 만료되었으면 재요청에 `details.reason = FILE_EXPIRED`가 포함된 `400 INVALID_REQUEST`를 반환하므로, 새 키로 다시 업로드하세요.

## 다운로드

각 작업 결과에는 인증 정보 없이 1시간 동안 사용할 수 있는 `download_url`이 포함됩니다. 새 링크가 필요하면 작업을 다시 조회하세요. 인증 정보를 포함한 `GET /files/{file_id}`로 내 파일을 다운로드할 수 있습니다. 파일은 항상 첨부 파일로 제공됩니다.

서명된 `download_url`은 만료되거나 변경되면 `404 NOT_FOUND`를 반환합니다. 이용 정지 또는 삭제 중인 계정의 모든 링크도 같은 방식으로 사용할 수 없게 됩니다.

| 출력 | 입력으로 전달 가능한 곳 |
| --- | --- |
| PNG 또는 JPEG | 모든 이미지 엔드포인트(편집, 텍스트 감지, 업스케일, 변환, 참조 이미지) |
| WebP | 편집, 텍스트 감지, 업스케일, SVG 벡터화 및 참조 이미지. PNG, PDF, TIFF 또는 PPTX 변환에는 사용 불가 |
| 순서도 SVG | PNG, PDF, TIFF 또는 PPTX로 변환하는 `POST /images/conversions` |
| PDF, TIFF, EPS, PPTX 및 기타 SVG | 입력으로 사용 불가. 다운로드만 가능 |

20 MB보다 큰 변환 원본(예: 8K 업스케일 이미지)은 `400 INVALID_REQUEST`(`FILE_TOO_LARGE`)로 거부됩니다.

## cURL

```bash
curl -X POST https://scifig.ai/api/v1/files \
  -H "Authorization: Bearer $SCIFIG_API_KEY" \
  -F "file=@figure.png" \
  -F "purpose=image"
```

## JavaScript

```javascript
import { readFile } from 'node:fs/promises';

const form = new FormData();
form.set('file', new Blob([await readFile('figure.png')]), 'figure.png');
form.set('purpose', 'image');

const response = await fetch('https://scifig.ai/api/v1/files', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SCIFIG_API_KEY}`,
  },
  body: form,
});
const result = await response.json();
console.log(response.status, result);
```

## Python

```python
import os

import requests

headers = {
    "Authorization": f"Bearer {os.environ['SCIFIG_API_KEY']}",
}
response = requests.post(
    "https://scifig.ai/api/v1/files",
    headers=headers,
    files={"file": open("figure.png", "rb")},
    data={"purpose": "image"},
    timeout=60,
)
print(response.status_code, response.json())
```