Batch Files

Batch에 사용할 입력 파일을 업로드하고, 결과 및 오류 파일을 내려받으세요.

파일을 다루는 API이며, 실행 작업의 생성과 상태 조회는 Batches API에서 합니다.

POSThttps://gw.letsur.ai/v1/files

AUTHAuthorization: Bearer <API_KEY>

지원 동작

업로드는 파일을 만들고 외부 AI 제공업체로 전달합니다. 실행 작업은 Batches에서 따로 생성합니다.

Base URL은 https://gw.letsur.ai입니다. AI 게이트웨이 API 키를 사용합니다.

동작	메서드와 경로
입력 업로드	`POST /v1/files`
파일 정보 조회	`GET /v1/files/{file_id}`
파일 콘텐츠 다운로드	`GET /v1/files/{file_id}/content`

파일 목록과 삭제 API는 제공하지 않습니다. 영상이나 이미지용 References와는 다른 자원입니다.

처음 실행한다면 Batch 가이드의 시작 조건과 한 줄 시험을 따릅니다. 이미 파일이나 작업 ID가 있다면 다음 단계로 이동하세요.

입력 업로드

업로드 시 외부 AI 제공업체로 전달됩니다. 이후 Batch 제출이 거부되거나 제출하지 않아도 이미 이루어진 외부 전달이 취소되는 것은 아닙니다.

공개된 처리 업체와 이전 범위는 데이터 처리 위탁 현황에서 확인합니다.

multipart/form-data로 file과 purpose=batch를 전송합니다. 파일은 JSONL이며 각 행은 다음 구조를 사용합니다.


{
  "custom_id": "request-1",
  "method": "POST",
  "url": "/v1/chat/completions",
  "body": {
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "안녕하세요"}],
    "service_tier": "default"
  }
}

위 예시는 읽기 쉽게 펼친 한 행입니다. 실제 JSONL에는 한 JSON 객체를 한 줄로 작성합니다. 모델의 Batch 지원 여부는 Models API의 supports_batch에서 확인합니다. 지원 API와 입력 조건도 함께 확인해야 합니다.

파일당 최대 50,000행, 200,000,000바이트입니다.
Embeddings는 파일 전체의 embedding 입력 합계도 최대 50,000개입니다. 예를 들어 각 행에 문자열 100개를 넣은 501행은 입력 50,100개이므로 거부됩니다.
Embeddings의 input에 배열을 쓰면 각 배열은 최대 2,048개 원소를 가집니다. 토큰 ID 배열 하나는 embedding 입력 1개로 세지만 배열 원소 제한도 적용됩니다. 토큰 ID 배열의 배열은 바깥 배열과 각 안쪽 배열 모두 이 제한을 지킵니다.
한 파일은 같은 모델과 endpoint를 사용하며 custom_id는 중복될 수 없습니다.
모델과 endpoint의 불일치, 미지원 필드 등은 업로드에서 거부될 수 있습니다.
모델별 Chat 파라미터 차이와 컨텍스트 초과를 모두 사전 검증하는 것은 아닙니다. 입력 작성 시 주의점을 확인합니다.

업로드를 다시 요청할 때

재사용 범위는 같은 스페이스와 같은 소유 주체입니다. 개인 키의 소유 주체는 사람이며, 공유 키의 소유 주체는 해당 키 자체입니다. 파일 내용은 JSON의 뜻이 아니라 실제 바이트로 비교하므로 공백이나 줄바꿈이 바뀌어도 다른 파일로 판단할 수 있습니다.

업로드 조건	결과와 다음 행동
`Idempotency-Key` 헤더 없음	동일 바이트의 파일은 1시간의 중복 확인 범위에서 파일 ID를 재사용할 수 있습니다. 동시 업로드의 중복까지 방지하지는 않습니다.
같은 명시 키와 같은 바이트, 24시간 계약 안	저장된 업로드 결과를 반환합니다. 성공했다면 같은 파일 ID를 받고, 저장된 업로드 실패라면 그 실패를 다시 받습니다.
같은 명시 키인데 바이트가 다름	`409 idempotency_conflict`. 원래 업로드를 확인하려면 원래 파일을 보내고, 바꾼 파일을 올리려면 새 키를 사용합니다.
같은 키의 업로드가 아직 미확정	`409 idempotency_in_flight`. 잠시 기다렸다가 같은 키와 파일로 다시 요청합니다.
빈 문자열 또는 공백뿐인 키	`400 idempotency_key_invalid`. 키를 쓰지 않으려면 헤더를 생략합니다.

24시간을 넘긴 명시 키의 재요청은 중복 방지를 보장하지 않습니다. 저장된 업로드 실패를 받았다면 오류 원인을 먼저 확인합니다. 업로드를 새로 수행하려는 경우 새 키를 사용하며, 응답 유실이나 진행 중 상태에서 무작정 키를 바꾸지 않습니다.

파일 재사용은 새 Batch 실행을 막지 않습니다. 업로드 키와 Batch 제출 키는 별도 요청에 적용됩니다. 제출의 재시도는 Batches를 따릅니다.

파일 정보와 콘텐츠

입력 파일: 업로드 응답의 id를 작업 생성의 input_file_id에 사용합니다.
결과 및 오류 파일: Batch 조회의 output_file_id 또는 error_file_id를 조회와 다운로드에 사용합니다.

필드	의미
`id`	게이트웨이 파일 ID
`object`	`file`
`filename`	파일 이름
`purpose`	파일 용도
`bytes`	파일 크기. 미확인 시 null, 실제 빈 파일은 0
`created_at`	생성 시각

GET /v1/files/{file_id}/content는 파일 본문을 반환합니다. 결과 및 오류 파일은 JSONL로 읽고 각 행의 custom_id로 입력과 연결합니다.

파일 ID가 없을 때

처리 완료 직후: 결과 파일 ID는 유닛 차감 뒤에 준비되므로 completed여도 없을 수 있습니다. 파일 ID가 없을 때의 다음 행동을 확인합니다.
정산 완료 뒤: 해당 종류의 결과가 없으면 한쪽 파일 ID는 null일 수 있습니다.

반환된 파일 ID가 있으면 다운로드합니다. 다운로드 API는 settled를 별도 조건으로 검사하지 않습니다. 비용 확정은 settlement_status와 settled_units로 따로 확인합니다.

ID가 있는데 다운로드되지 않는다면 보관 기한과 접근 권한을 확인합니다.

파일 보관과 만료

결과 파일은 Batch 완료 후 30일이 지나면 만료됩니다. 준비되는 즉시 내려받아 별도로 보관하세요.

보관 기간을 지정하는 기능은 없습니다.
output_file_id가 남아 있어도 다운로드 가능을 뜻하지 않습니다. 만료된 파일의 복구를 전제로 연동하지 않습니다.
completion_window: "24h"는 요청 처리 창입니다. Batch의 expires_at도 결과 파일의 다운로드 만료 시각으로 사용하지 않습니다.

접근과 오류

본인이 사용할 권한이 있는 파일만 조회하고 다운로드할 수 있습니다. 다른 스페이스의 파일 ID를 알아도 접근할 수 없습니다.

접근 방식	파일 접근 범위
개인 API 키	같은 스페이스의 해당 소유자 파일
공유 API 키	같은 스페이스의 해당 키 파일
콘솔 관리자	같은 스페이스에서 사람 소유자 정보가 기록된 결과 및 오류 파일. 타인의 Batch 취소 권한은 아님

API에서는 현재 스페이스와 파일에 접근할 수 있는 유효한 키를 사용합니다. 콘솔 관리자 권한을 API 키에 적용하지 않습니다.

invalid_line: 표시된 행과 사유를 수정합니다.
파일을 찾거나 받을 수 없음: 응답만으로 파일의 존재 여부를 판단하지 않습니다. Batch ID, 파일 ID, 요청 시각과 오류 코드를 플랫폼 내 문의 기능으로 전달합니다. API 키는 보내지 않습니다.