--- title: 파일 및 업로드 | RunAPI description: 영구 파일을 생성, 목록 조회, 다운로드, 삭제하거나 멀티파트 업로드 파트로 파일을 조합합니다. url: https://runapi.ai/ko/docs/resources/files.md canonical: https://runapi.ai/ko/docs/resources/files locale: ko --- > HTML 버전: https://runapi.ai/ko/docs/resources/files > 에이전트용 사이트 색인: https://runapi.ai/llms.txt # 파일 및 업로드 Files API는 변경 불가능한 계정 범위의 `user_data`, `batch`, `batch_output` File을 저장하고, 스토리지 URL 대신 안정적인 File ID를 반환합니다. 재사용 가능한 File 리소스를 허용하는 API에는 File ID를 사용하고, 정확한 저장 바이트가 필요한 경우에는 콘텐츠 엔드포인트를 사용하세요. ## 업로드 흐름 선택 * `POST /v1/files`를 사용하여 하나의 멀티파트 요청으로 File을 생성하십시오. 완료된 `user_data` File은 최대 `52,428,800` 바이트를 포함할 수 있습니다. * 직접 배치 입력의 경우 `purpose=batch`와 함께 `POST /v1/files`를 사용하십시오. 최대 `95,000,000` 바이트까지 가능합니다. * Uploads API를 사용하여 최종 File을 구성하기 전에 Parts를 전송하십시오. 각 Part는 최대 `67,108,864` 바이트를 포함할 수 있으며, 완료된 `user_data` File은 `52,428,800` 바이트, 완료된 `batch` File은 `209,715,200` 바이트로 제한됩니다. 미완료 Upload는 1시간 후 만료됩니다. * 활성 File과 진행 중인 예약은 계정 스토리지 한도 `5,368,709,120` 바이트를 공유합니다. `POST /api/v1/files`는 임시 URL을 반환하는 별도의 임시 업로드 흐름입니다. SDK `files.create`와 CLI `runapi files create`는 계속 해당 흐름을 사용합니다. 영구 File 객체가 필요한 경우 `files.createFile` 또는 `files.create_file`을 사용하거나, CLI에서는 `runapi files create-file`을 사용하세요. ## 요청 인증 파일 및 업로드는 표준 RunAPI API 키를 사용합니다. Bearer 토큰으로 전송하세요: ```shell export RUNAPI_API_KEY="runapi_..." ``` 모든 파일, 업로드, 파트, 콘텐츠 요청은 인증된 계정으로 범위가 제한됩니다. 다른 계정이 소유한 ID는 해당 리소스의 존재 여부를 노출하지 않고 `404`를 반환합니다. ## 호환 클라이언트로 File 만들기 OpenAI 호환 클라이언트를 RunAPI `/v1` 기본 URL로 지정하세요. RunAPI 전용 요청 필드는 필요하지 않습니다: ```python import os from openai import OpenAI client = OpenAI( api_key=os.environ["RUNAPI_API_KEY"], base_url="https://runapi.ai/v1", ) with open("knowledge.pdf", "rb") as source: file = client.files.create(file=source, purpose="user_data") metadata = client.files.retrieve(file.id) client.files.content(file.id).write_to_file("knowledge-copy.pdf") client.files.delete(file.id) ``` 반환된 File에는 스토리지 식별자, 백엔드 또는 bearer URL이 포함되지 않습니다. ## API 참조 * [Persistent Files API](https://runapi.ai/ko/docs/api/protocol/files.md)는 File 객체와 생성, 목록 조회, 조회, 콘텐츠 및 삭제 작업을 다룹니다. * [Uploads API](https://runapi.ai/ko/docs/api/protocol/uploads.md)는 Upload 객체와 생성, 파트 추가, 완료 및 취소 작업을 다룹니다. * [Batches API](https://runapi.ai/ko/docs/api/protocol/batches.md)는 Moderation Batch 생성, 상태 조회, 목록 조회 및 취소를 다룹니다. ## 배치에서 모더레이션 실행 줄마다 하나의 검수 요청이 포함된 JSONL 입력 File을 만듭니다. 각 줄은 호환되는 Batch 형식을 사용합니다: `custom_id`, `method`, `/v1/moderations`로 설정된 `url`, 그리고 검수 모델과 입력이 포함된 `body`. `purpose=batch` File은 최대 50,000개의 요청을 포함할 수 있습니다. Batch 기능은 현재 `24h` 완료 기간으로 `/v1/moderations` 엔드포인트를 허용합니다. ```shell INPUT_FILE_ID=$(curl -sS https://runapi.ai/v1/files \ -H "Authorization: Bearer $RUNAPI_API_KEY" \ -F purpose=batch \ -F file=@moderation.jsonl | jq -r .id) BATCH_ID=$(curl -sS https://runapi.ai/v1/batches \ -H "Authorization: Bearer $RUNAPI_API_KEY" \ -H "Content-Type: application/json" \ -d "$(jq -n --arg file "$INPUT_FILE_ID" '{input_file_id:$file,endpoint:"/v1/moderations",completion_window:"24h"}')" \ | jq -r .id) curl -sS "https://runapi.ai/v1/batches/$BATCH_ID" \ -H "Authorization: Bearer $RUNAPI_API_KEY" ``` 작업 목록을 확인하려면 `GET /v1/batches`를 사용하고, 상태가 종료 상태가 될 때까지 `GET /v1/batches/{batch_id}`를 반복하거나, 아직 실행 중인 경우 `POST /v1/batches/{batch_id}/cancel`을 호출하세요. 완료된 출력 및 오류 JSONL은 `batch_output` Files로 노출되며, `GET /v1/files/{file_id}`로 메타데이터를, `GET /v1/files/{file_id}/content`로 정확한 바이트를 가져올 수 있습니다. ## 멀티파트 업로드 라이프사이클 최종 바이트 수, 파일 이름, MIME 유형, `purpose=user_data`로 Upload를 만듭니다. 하나 이상의 Part를 추가한 후 구성 순서대로 해당 ID를 `complete`에 전달합니다. 완료 시 완성된 File과 함께 Upload가 반환됩니다. ```shell UPLOAD_ID=$(curl -sS https://runapi.ai/v1/uploads \ -H "Authorization: Bearer $RUNAPI_API_KEY" \ -H "Content-Type: application/json" \ -d '{"bytes":1048576,"filename":"archive.bin","mime_type":"application/octet-stream","purpose":"user_data"}' \ | jq -r .id) PART_ID=$(curl -sS "https://runapi.ai/v1/uploads/$UPLOAD_ID/parts" \ -H "Authorization: Bearer $RUNAPI_API_KEY" \ -F data=@archive.part-01 | jq -r .id) curl -sS "https://runapi.ai/v1/uploads/$UPLOAD_ID/complete" \ -H "Authorization: Bearer $RUNAPI_API_KEY" \ -H "Content-Type: application/json" \ -d "{\"part_ids\":[\"$PART_ID\"]}" ``` `POST /v1/uploads/{upload_id}/cancel`로 완료되지 않은 Upload를 취소합니다. 동일한 완료 의도 또는 취소를 반복해도 안전합니다. 경쟁하는 완료, 취소, 또는 만료는 다른 터미널 결과가 이미 적용된 경우 `409 upload_state_conflict`를 반환합니다. ## CLI 및 SDK 리소스 CLI는 전체 생명주기를 노출합니다: ```shell runapi files create-file knowledge.pdf runapi files list --order desc runapi files retrieve file_123 runapi files content file_123 --output knowledge-copy.pdf runapi files delete file_123 runapi uploads create --bytes 1048576 --filename archive.bin --mime-type application/octet-stream runapi uploads add-part upload_123 archive.part-01 runapi uploads complete upload_123 --part-id part_123 runapi uploads cancel upload_123 ``` 모든 Provider Client는 `files`와 `uploads`를 노출합니다. JavaScript와 PHP는 `createFile` / `deleteFile` / `addPart`를 사용하고, Python과 Ruby는 `create_file` / `delete_file` / `add_part`를 사용하며, Go는 `CreateFile` / `DeleteFile` / `AddPart`를 사용하고, Java는 `createFile` / `deleteFile` / `addPart`를 사용합니다. 목록 조회, 검색, 콘텐츠, 생성, 완료, 취소는 각 언어의 일반 명명 규칙을 따릅니다. 패키지 설치는 [SDKs](https://runapi.ai/ko/docs/resources/sdks.md)를 참조하세요. ## 라이프사이클 동작 파일 콘텐츠는 변경 불가능합니다. 파일을 삭제하면 활성 목록에서 즉시 제거되고 스토리지 정리가 예약됩니다. 업로드 완료는 제공된 순서대로만 파트를 조합하며, 성공적인 완료는 하나의 파일을 생성합니다. 불확실한 완료 응답을 재시도할 때 원래 파트 ID 순서를 유지하세요. --- ## RunAPI의 더 많은 정보 - [홈](https://runapi.ai/ko/.md) - [모델 카탈로그](https://runapi.ai/ko/models.md) - [요금](https://runapi.ai/ko/pricing.md) - [제공사](https://runapi.ai/ko/models) - [문서](https://runapi.ai/ko/docs/guides) - [SDK](https://runapi.ai/ko/sdk.md) - [CLI](https://runapi.ai/ko/cli.md) - [MCP Server](https://runapi.ai/ko/mcp.md) - [Claude Code와 Cursor](https://runapi.ai/ko/claude-code-vs-cursor.md) - [Cursor API 설정](https://runapi.ai/ko/cursor-api-setup.md) - [RunAPI와 OpenRouter 비교](https://runapi.ai/ko/openrouter-alternative.md) - [엔터프라이즈](https://runapi.ai/ko/contact.md) - [문의](https://runapi.ai/ko/contact.md) - [약관](https://runapi.ai/ko/terms.md) - [개인정보](https://runapi.ai/ko/privacy.md) - [에이전트용 사이트 색인](https://runapi.ai/llms.txt) 문의: contact@runapi.ai ## 구조화된 데이터 ```json [ { "@context": "https://schema.org", "inLanguage": "ko", "@type": "WebSite", "name": "RunAPI", "url": "https://runapi.ai/ko", "potentialAction": { "@type": "SearchAction", "target": { "@type": "EntryPoint", "urlTemplate": "https://runapi.ai/ko/models?q={search_term_string}" }, "query-input": "required name=search_term_string" } }, { "@context": "https://schema.org", "inLanguage": "ko", "@type": "Organization", "name": "RunAPI", "url": "https://runapi.ai/ko", "logo": { "@type": "ImageObject", "url": "https://runapi.ai/koicon.svg" }, "sameAs": [ "https://github.com/runapi-ai" ] }, { "@context": "https://schema.org", "inLanguage": "ko", "@type": "TechArticle", "headline": "파일 및 업로드", "description": "영구 파일을 생성, 목록 조회, 다운로드, 삭제하거나 멀티파트 업로드 파트로 파일을 조합합니다.", "url": "https://runapi.ai/ko/docs/resources/files", "mainEntityOfPage": "https://runapi.ai/ko/docs/resources/files" } ] ```