개발자 리소스

파일 및 업로드

영구 파일을 생성, 목록 조회, 다운로드, 삭제하거나 멀티파트 업로드 파트로 파일을 조합합니다.

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는 File 객체와 생성, 목록 조회, 조회, 콘텐츠 및 삭제 작업을 다룹니다.
Uploads API는 Upload 객체와 생성, 파트 추가, 완료 및 취소 작업을 다룹니다.
Batches API는 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 [email protected] | 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 [email protected] | 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를 참조하세요.

라이프사이클 동작

파일 콘텐츠는 변경 불가능합니다. 파일을 삭제하면 활성 목록에서 즉시 제거되고 스토리지 정리가 예약됩니다. 업로드 완료는 제공된 순서대로만 파트를 조합하며, 성공적인 완료는 하나의 파일을 생성합니다. 불확실한 완료 응답을 재시도할 때 원래 파트 ID 순서를 유지하세요.