본문으로 건너뛰기

Batch Files

Batch 입력 파일 업로드와 결과 다운로드

JSONL 입력 조건과 업로드 재시도, 파일 조회 및 접근 범위를 설명하고, Batches의 작업 생성과 구분되는 파일 처리 과정을 안내합니다.

페이지 목차

API 목록

Batch에 사용할 입력 파일을 업로드하고, 입력 파일, 결과 파일과 오류 파일의 정보를 조회하거나 내용을 다운로드할 수 있습니다.

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

파일 목록과 삭제 API는 제공하지 않습니다. Batch 파일은 영상이나 이미지용 References로 업로드한 파일과 다릅니다.

Batch를 처음 실행한다면 Batch 가이드에서 시작 조건을 확인한 뒤 한 줄 입력으로 시험하는 절차를 따르세요.

입력 파일 업로드

POST
https://gw.letsur.ai/v1/files
인증Authorization: Bearer <API_KEY>

multipart/form-data 형식으로 file 파트와 purpose=batch 필드를 보냅니다. 파일은 JSONL 형식으로 작성합니다. 각 행에 작성할 JSON 객체의 구조는 다음과 같습니다. 다음은 예시 모델 gpt-4o-mini로 Chat Completions를 호출하는 행입니다. 다른 모델이나 API에서는 API별 입력 조건과 모델별 입력 조건에 맞게 body를 바꿉니다.

{ "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개
Embeddings의 input에 지정한 배열의 원소 수배열마다 최대 2,048개

예를 들어 Embeddings 입력의 각 행에 문자열 100개를 포함한 501행 파일은 입력 합계가 50,100개이므로 거부됩니다. 토큰 ID 배열 하나는 embedding 입력 1개로 계산되지만 배열 원소 제한도 적용됩니다. 토큰 ID 배열을 중첩하면 바깥 배열과 각 안쪽 배열에 모두 원소 제한이 적용됩니다.

입력을 작성할 때는 다음도 확인합니다.

  • 한 파일의 모든 요청은 같은 모델과 endpoint를 사용해야 하며, 각 요청의 custom_id는 서로 달라야 합니다.
  • 모델과 endpoint가 일치하지 않거나 지원되지 않는 필드가 있으면 업로드 요청이 거부될 수 있습니다.
  • 게이트웨이가 처리 전에 모델마다 다른 Chat Completions 파라미터와 컨텍스트 초과를 모두 검증하지는 않습니다. 아래 API별 입력 조건과 모델별 입력 조건을 확인합니다.

API별 입력 조건

실시간 API에서 성공한 요청도 Batch에서는 실패할 수 있습니다. Batch에서는 입력 파라미터가 실시간 호출처럼 변환되지 않습니다.

출력 상한은 선택 항목입니다. 출력 상한을 두려면 사용하는 API에 맞는 필드를 씁니다.

APIservice_tier출력 상한 필드
Chat Completions"default" 명시모델에 따라 max_tokens 또는 max_completion_tokens. 모델별 입력 조건 참고
Responses"default" 명시max_output_tokens
Embeddings지정하지 않음지정하지 않음

Responses 입력에 max_tokens나 max_completion_tokens를 지정하면 업로드가 invalid_line (400) 오류의 unknown_field 사유로 거부됩니다.

Chat Completions에서 모델이 지원하지 않는 출력 필드를 보내면 업로드와 제출은 성공해도 처리 뒤 모든 행이 실패할 수 있습니다.

stream, stream_options, functions, function_call, audio, modalities, prediction, web_search_options, store는 Batch 입력에 사용할 수 없습니다.

모델별 입력 조건

Batch 입력의 다음 조건은 모델에 따라 달라집니다.

  • 출력 상한 필드: Chat Completions 입력에서 출력 상한을 지정하는 필드는 모델에 따라 max_tokens 또는 max_completion_tokens입니다. max_completion_tokens를 쓰는 모델에 max_tokens를 지정한 요청은 업로드를 통과해도 처리 중 실패할 수 있습니다.
  • Responses 입력에 필요한 도구: 일부 모델은 Responses 입력에 web_search 도구가 있어야 합니다. 이 도구가 없으면 업로드가 invalid_line (400) 오류의 endpoint_requires_web_search 사유로 거부됩니다.
  • Responses 전용 모델: 지원 endpoint가 Responses뿐인 모델은 Chat Completions로 제출하지 않습니다. Responses 전용 모델인지는 모델의 지원 endpoint에서 확인합니다.

각 조건이 적용되는 모델은 다음과 같습니다. 이 표의 조건은 표에 적힌 모델에만 적용됩니다.

모델API조건
GPT-4o 및 GPT-4.1 계열Chat Completions출력 상한에 max_tokens 사용
GPT-5 계열Chat Completions출력 상한에 max_completion_tokens 사용. max_tokens를 지정하면 업로드를 통과해도 처리 중 실패할 수 있음
gpt-5.2-pro, gpt-5.5-pro 및 정책상 허용된 날짜 스냅샷 IDResponsesResponses의 기본 허용 모델
gpt-4.1, gpt-4.1-mini, gpt-5.5, gpt-5.6-solResponsestools: [{"type": "web_search"}] 필요

입력 파일 업로드 예시

다음 예제는 cURL이나 Python에서 input.jsonl을 업로드합니다. 서버 환경 변수 LETSUR_API_KEY와 위 조건을 만족하는 입력 파일을 준비합니다.

아래 업로드 예제는 Idempotency-Key를 생략합니다. 이미 요청 키를 사용한 업로드의 응답을 다시 확인하려면 Batch 가이드의 업로드 절차에 따라 같은 요청 키와 파일을 유지하세요.

Python 예제는 Python 3에서 실행합니다. 예제는 요청을 자동으로 재시도하지 않습니다. 오류 응답이나 서명 링크가 포함된 출력은 공개 로그에 남기지 마세요.

업로드한 파일은 즉시 외부 AI 제공업체로 전달됩니다

이후 Batch를 제출하지 않거나 제출이 거부되더라도, 이미 이루어진 파일 전달은 취소되지 않습니다. 업로드하기 전에 파일 내용을 확인하세요. 파일을 전달받는 공개된 처리 업체와 이전 범위는 데이터 처리 위탁 현황에 있습니다.

cURL
curl --fail-with-body "https://gw.letsur.ai/v1/files" \ -H "Authorization: Bearer $LETSUR_API_KEY" \ -F 'purpose=batch' \ -F 'file=@input.jsonl'

성공 응답에서 id를 읽습니다. 다음은 필요한 필드만 남긴 설명용 예시입니다.

{"id":"file_example","object":"file","filename":"input.jsonl","purpose":"batch","bytes":256,"created_at":1730000000}

이 id 값을 Batches 생성 본문의 input_file_id에 지정합니다. 업로드 응답이 유실됐거나 업로드를 다시 해야 한다면 아래 조건을 먼저 확인합니다.

업로드를 다시 요청할 때

업로드 결과는 같은 스페이스 안에서, 개인 키라면 같은 사람이, 공유 키라면 같은 키로 요청할 때만 재사용할 수 있습니다. 게이트웨이는 파일 내용을 바이트 단위로 비교합니다. JSON 데이터의 의미가 같아도 공백이나 줄바꿈이 바뀌면 다른 파일로 판단될 수 있습니다.

업로드 조건결과와 다음 행동
Idempotency-Key 헤더 없음중복 확인 범위인 1시간 안에 같은 바이트의 파일을 업로드하면 기존 파일 ID가 재사용될 수 있습니다. 동시에 보낸 업로드의 중복은 방지되지 않습니다.
24시간 이내에 같은 Idempotency-Key와 같은 파일 바이트로 재요청게이트웨이가 저장된 업로드 결과를 반환합니다. 원래 업로드가 성공했다면 같은 파일 ID가, 실패했다면 같은 실패가 다시 반환됩니다.
같은 Idempotency-Key인데 파일 바이트가 다름idempotency_conflict (409). 원래 업로드를 확인하려면 원래 파일을 보내고, 수정한 파일을 업로드하려면 새 키를 사용합니다.
같은 키의 업로드가 아직 미확정idempotency_in_flight (409). 잠시 후 같은 키와 파일로 다시 요청합니다.
빈 문자열 또는 공백뿐인 키idempotency_key_invalid (400). 키를 사용하지 않으려면 헤더를 생략합니다.

Idempotency-Key를 다룰 때는 다음을 알아 두세요.

  • 같은 Idempotency-Key로 24시간을 넘겨 다시 요청하면 중복 방지가 보장되지 않습니다.
  • 저장된 업로드 실패를 받았다면 오류 원인을 먼저 확인합니다. 새로 업로드하려면 새 키를 사용합니다.
  • 응답 유실이나 진행 중 상태를 이유로 키를 바꾸지 않습니다.

파일 재사용은 새 Batch 실행을 막지 않습니다. 업로드 키와 Batch 제출 키는 별도 요청에 적용됩니다. Batch 제출을 재시도하는 방법은 Batches에서 확인합니다.

파일 조회와 다운로드

  • 입력 파일: 업로드 응답의 id를 작업 생성의 input_file_id에 지정합니다.
  • 결과 및 오류 파일: Batch 조회 응답의 output_file_id 또는 error_file_id로 파일을 조회하고 다운로드합니다.

파일 정보 조회하기

GET
https://gw.letsur.ai/v1/files/{file_id}
인증Authorization: Bearer <API_KEY>

파일 ID를 지정해 아래 메타데이터를 조회합니다. 접근 권한이 있는 파일에 AI 게이트웨이 API 키로 요청합니다. 이 API는 파일 크기와 이름 등의 메타데이터만 반환하며, 응답에 파일 내용은 포함되지 않습니다.

서버 환경 변수 LETSUR_API_KEY와 FILE_ID를 준비합니다. 아래 예제는 한 번만 요청하며 자동으로 재시도하지 않습니다.

cURL
curl --fail-with-body "https://gw.letsur.ai/v1/files/$FILE_ID" \ -H "Authorization: Bearer $LETSUR_API_KEY"
필드설명
id게이트웨이 파일 ID
objectfile
filename파일 이름
purpose파일 용도
bytes파일 크기. 확인하지 못하면 null, 실제 빈 파일은 0
created_at생성 시각

파일 내용 다운로드

GET
https://gw.letsur.ai/v1/files/{file_id}/content
인증Authorization: Bearer <API_KEY>

파일 ID로 파일 내용을 다운로드합니다. 접근 권한이 있는 파일에 AI 게이트웨이 API 키로 요청합니다. 결과 및 오류 파일은 JSONL로 읽고 각 행의 custom_id로 입력과 연결합니다. 각 행의 response.status_code, response.body와 error에 요청별 처리 결과가 포함됩니다.

서버 환경 변수 LETSUR_API_KEY와 FILE_ID를 준비합니다. 아래 예제는 한 번만 요청하며 자동으로 재시도하지 않습니다. cURL 예제는 응답 본문을 터미널에 표시합니다. 파일로 저장하려면 Python 예제를 사용하세요. Python 예제는 batch-result.jsonl이 이미 있으면 그 파일을 덮어쓰지 않습니다.

cURL
curl --fail "https://gw.letsur.ai/v1/files/$FILE_ID/content" \ -H "Authorization: Bearer $LETSUR_API_KEY"

파일 ID가 없을 때

  • 처리 완료 직후: 결과 파일 ID는 유닛 차감 뒤에 준비되므로 status가 completed여도 아직 없을 수 있습니다. 파일 ID가 없을 때의 다음 행동을 확인합니다.
  • 정산 완료 뒤: 결과 파일이나 오류 파일에 포함할 결과가 없으면 그 파일의 ID는 null일 수 있습니다.

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

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

파일 보관과 만료

결과 파일은 Batch 완료 30일 뒤 만료됩니다

준비되는 즉시 다운로드해 별도로 보관하세요.

  • 보관 기간을 지정하는 기능은 없습니다.
  • output_file_id가 남아 있어도 만료된 파일은 다운로드하지 못할 수 있습니다. 만료 후 복구에 의존하지 않도록 기한 안에 다운로드하세요.
  • completion_window: "24h"는 Batch 요청의 처리 기간이며 결과 파일의 다운로드 기한이 아닙니다. Batch의 expires_at도 결과 파일의 다운로드 만료 시각이 아닙니다.

위 30일은 결과 파일의 만료 기준입니다. 입력 파일의 보관 기간이나 모든 사본의 물리 삭제 완료 시점을 뜻하지 않습니다.

보관 조건을 확인하거나 파일 삭제를 요청하려면 플랫폼 내 문의 기능에 다음 정보를 남기세요.

  • 파일 ID
  • 관련 Batch ID(있는 경우)

파일 원문이나 API 키는 보내지 마세요. 렛서는 요청 권한과 적용 조건을 확인한 뒤 가능한 조치와 처리 결과를 안내합니다.

공통 처리 조건과 요청 절차는 이용약관 제13조 및 부속서 1 , 개인정보에 관한 권리 행사는 개인정보 처리방침 제8조 를 따릅니다.

파일 접근 권한

본인이 사용할 권한이 있는 파일만 조회하고 다운로드할 수 있습니다. 다른 스페이스의 파일 ID를 알아도 접근할 수 없습니다. 개인 키와 공유 키, 콘솔 역할별 접근 범위는 Batch 가이드의 콘솔과 API 키의 접근 범위에서 확인합니다.

API에서는 현재 스페이스와 파일에 접근할 수 있는 유효한 키를 사용합니다. 콘솔 관리자 권한은 API 키에 적용되지 않습니다. 콘솔 관리자가 다운로드할 수 있는 파일은 같은 스페이스에서 사람 소유자 정보가 기록된 결과 및 오류 파일입니다.

오류와 복구

업로드 재시도에서 받는 idempotency_conflict (409), idempotency_in_flight (409), idempotency_key_invalid (400)의 처리는 업로드를 다시 요청할 때의 표에 있습니다. 그 밖의 오류는 다음과 같이 처리합니다.

  • invalid_line: 표시된 행과 사유를 수정합니다. 사유가 unknown_field라면 API별 입력 조건의 출력 상한 필드를, endpoint_requires_web_search라면 모델별 입력 조건의 도구 조건을 확인합니다.
  • 파일을 찾거나 받을 수 없음: 응답만으로 파일의 존재 여부를 판단하지 않습니다. Batch ID, 파일 ID, 요청 시각과 오류 코드를 플랫폼 내 문의 기능으로 전달합니다. API 키는 보내지 않습니다.