본문으로 건너뛰기

Batches

Batch 작업 생성, 상태 조회와 취소

작업 생성과 재시도 조건, 키별 접근 범위, 목록 및 취소 요청을 설명하고, 처리 상태와 결과 파일 및 확정 비용을 읽는 필드를 안내합니다.

페이지 목차

요청 경로와 인증

Batch는 입력 파일에 기록된 여러 API 요청을 비동기로 처리합니다. 업로드한 파일 ID로 작업을 생성하고, 응답의 Batch ID로 상태를 조회하거나 취소를 요청할 수 있습니다.

Base URL은 https://gw.letsur.ai입니다. AI 게이트웨이 API 키를 Bearer 헤더로 전달합니다. 키 설정은 인증과 요청 헤더에서 확인합니다.

Batch ID는 생성 응답의 id입니다. 작업 ID(/v1/jobs에서 쓰는 ID)나 공급사의 원본 ID와는 다른 값이므로 서로 바꿔 넣지 마세요.

Batch 생성

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

Batch는 초과 유닛 사용이 허용된 스페이스에서만 생성할 수 있습니다. 허용되지 않은 스페이스에서는 보유 유닛과 관계없이 게이트웨이가 HTTP 403을 반환합니다. 유닛을 구매하는 것만으로는 이 거부가 풀리지 않습니다. 오류 응답의 코드는 오류와 복구에 있습니다.

  • 제출 전 확인: 스페이스 관리자(Admin)에게 이용 조건을 확인합니다. 관리자도 확인할 수 없다면 플랫폼 내 문의 기능을 사용합니다.
  • 별도 사용 한도: API 키와 구성원의 사용 한도도 적용됩니다. 사용 한도를 확인합니다.

요청 본문의 필드는 다음과 같습니다. 요청 헤더의 Idempotency-Key는 선택 항목입니다. 사용 조건은 재실행과 재시도에서 확인합니다.

필드타입요구 여부설명
input_file_idstring필수Batch Files로 업로드한 파일의 ID
endpointstring필수/v1/chat/completions, /v1/responses, /v1/embeddings 중 모델이 지원하는 경로. 파일의 모든 행이 사용하는 API 경로
completion_windowstring필수"24h"만 허용
metadataobject 또는 null선택키와 값은 문자열. 한도는 metadata에서 확인
{ "input_file_id": "FILE_ID", "endpoint": "/v1/chat/completions", "completion_window": "24h", "metadata": {"task": "classification"} }

FILE_ID는 자리표시자입니다. 업로드 응답의 파일 ID로 바꾸세요.

제출하기 전에 다음을 확인합니다.

  • endpoint 값: 파일 업로드 때 검증된 경로와 같아야 합니다. 다르면 endpoint_mismatch (400)가 반환됩니다. 업로드한 뒤 모델 지원 정책이 바뀌어도 Batch 생성 요청이 거부될 수 있습니다.
  • 출력 상한 필드: 입력 파일의 body에서 출력 상한을 지정하는 필드는 모델과 API마다 다릅니다. 실시간 호출의 본문을 옮기기 전에 Batch Files의 API별 입력 조건과 모델별 입력 조건을 확인하세요.
  • completion_window: 24h는 요청을 처리하는 기간입니다. 정확한 완료 시각이나 성공을 보장하지 않습니다. 처리 기간이 지난 작업은 expired 상태가 될 수 있습니다.

생성 요청 예시

아래 cURL과 Python 예시는 Chat Completions 입력 파일 기준입니다. Responses나 Embeddings 입력 파일이면 endpoint를 그 API의 경로로 바꿉니다. input_file_id를 실제 업로드 응답의 ID로 바꾸고, 서버 환경 변수 LETSUR_API_KEY를 준비합니다. BATCH_REQUEST_KEY에는 이번 제출을 식별할 고유 문자열을 설정하세요. 원래 제출을 확인할 때는 이 값과 본문을 유지합니다.

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

cURL
curl --fail-with-body "https://gw.letsur.ai/v1/batches" \ -H "Authorization: Bearer $LETSUR_API_KEY" \ -H "Idempotency-Key: $BATCH_REQUEST_KEY" \ -H 'Content-Type: application/json' \ -d '{"input_file_id":"FILE_ID","endpoint":"/v1/chat/completions","completion_window":"24h"}'

생성 요청이 성공하면 응답의 Batch 객체에서 id를 읽어 저장합니다. 다음은 주요 필드만 남긴 설명용 예시입니다. 생성 직후의 상태가 항상 예시와 같다는 뜻은 아닙니다.

{"id":"batch_example","input_file_id":"file_example","endpoint":"/v1/chat/completions","status":"validating","output_file_id":null,"error_file_id":null,"settlement_status":"pending","settled_units":null}

이후 단건 조회에 같은 id를 사용합니다. 상태를 확인하기 위해 생성 POST 요청을 다시 보내지 않습니다.

재실행과 재시도

하려는 일요청 키와 결과
응답이 유실된 원래 제출 확인24시간 이내에 같은 Idempotency-Key와 같은 본문으로 요청합니다. 저장된 최초 제출 결과가 반환됩니다
같은 입력 또는 수정한 입력으로 새 실행새 키로 요청합니다. 새 작업과 비용이 생길 수 있습니다
키 없이 제출Idempotency-Key를 생략합니다. 제출할 때마다 새 Batch가 생성됩니다
같은 파일로 다시 제출해도 실행 중복은 막히지 않습니다

Idempotency-Key는 선택 헤더입니다. SDK가 이 헤더를 자동으로 추가한다고 가정하지 마세요. 요청이 진행 중이거나 응답이 없다는 이유로 키를 바꾸면 그 요청은 별도 실행으로 처리될 수 있습니다.

원래 제출을 확인할 때 유지할 값

  • 범위: 같은 스페이스에서 요청합니다. 개인 키는 사람을 기준으로 하므로 같은 사람이 요청하고, 공유 키는 키를 기준으로 하므로 같은 키로 요청합니다. 이 확인 요청으로 다른 사람이 개인 키로 제출한 작업이나 다른 공유 키로 제출한 작업은 조회할 수 없습니다.
  • 요청: 원래 Idempotency-Key, 파일 ID, endpoint, completion_window와 metadata를 유지합니다. 성공 응답의 Batch ID로 이후 상태를 조회합니다.
  • 기한: 24시간이 지난 뒤의 재시도에는 중복 방지가 보장되지 않습니다. 원래 제출 결과를 모르면 재제출 전에 작업 목록을 확인합니다. 목록만으로 원래 제출 결과를 판별할 수 없다면 요청 시각과 모델 정보를 준비해 플랫폼 내 문의 기능으로 지원을 요청합니다.

재시도 응답에 따른 행동

오류원인과 할 일
idempotency_in_flight (409)결과가 아직 확정되지 않았습니다. 잠시 후 같은 키와 본문으로 다시 요청합니다
idempotency_conflict (409)본문이 원래 요청과 다릅니다. 원래 제출을 확인하려면 원래 본문으로 되돌립니다
idempotency_key_invalid (400)빈 문자열 또는 공백뿐인 키입니다. 유효한 키를 지정합니다. 헤더를 생략하면 새 Batch가 생성됩니다
저장된 공급사 제출 실패원인을 확인합니다. 수정한 입력으로 새로 실행할 때는 새 키를 사용합니다

공급사 제출 실패가 저장된 경우에는 같은 키와 본문으로 다시 요청해도 같은 실패가 반환됩니다. 이 실패는 작업 생성 전 입력 검증에서 거절된 요청과 다릅니다.

예를 들어 classification-001 키로 보낸 요청의 응답이 유실됐다면 같은 키와 본문으로 다시 요청해 확인합니다. 입력을 수정해 새로 실행할 때만 classification-002처럼 새 키를 사용합니다.

metadata

요청에 지정한 metadata는 응답에 포함되고 공급사의 Batch 객체에도 전달됩니다. metadata를 전달해도 공급사 계정이나 대시보드에 접근할 권한은 생기지 않습니다.

조건한도 또는 오류
직접 지정한 키와 값 쌍최대 15개. 넘으면 metadata_too_many_entries
키 길이최대 64자. 넘으면 metadata_key_too_long
값 길이최대 512자. 넘으면 metadata_value_too_long
예약 키letsur_job_id 사용 불가. metadata_key_reserved

새로 제출할 때 위 표의 조건을 위반하면 게이트웨이가 HTTP 400을 반환합니다. 값이 문자열이 아니면 HTTP 422가 반환됩니다.

같은 Idempotency-Key와 본문으로 기존 요청의 결과를 받는 경우는 새 제출의 한도 검사와 구분합니다. 같은 키로 재시도하면서 metadata를 바꾸면 본문 충돌이 발생합니다.

빈 문자열인 키 이름({"": "v"})은 공급사가 거부하며, 이때 batch_provider_rejected (400)가 반환됩니다. 실패한 작업이 목록에 남을 수도 있습니다. 모든 metadata 오류가 metadata_* 코드로 반환된다고 가정하지 마세요.

Batch 단건 조회

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

생성 응답의 id인 Batch ID로 작업의 현재 상태를 조회합니다. 영상 작업 ID 대신 Batch ID를 사용합니다. 조회할 수 있는 작업의 범위는 API 키의 접근 범위에서 확인하세요.

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

cURL
curl --fail-with-body "https://gw.letsur.ai/v1/batches/$BATCH_ID" \ -H "Authorization: Bearer $LETSUR_API_KEY"

생성, 단건 조회와 취소 요청의 응답에 포함된 Batch 객체에서 아래 공통 필드를 확인합니다.

필드설명
id, input_file_id, endpoint작업, 입력 파일과 처리 API
status처리 상태. 값은 아래 status 표 참고
request_countstotal, completed, failed 요청 수. 확인할 수 없으면 null
output_file_id, error_file_id게이트웨이 결과 파일 ID. 준비 전이거나 해당 파일이 없으면 null
errorsBatch 오류 정보. 원인 확인에 사용
settlement_status정산 상태. 값은 아래 settlement_status 표 참고
settled_units정산이 끝나면 확정된 유닛 금액의 문자열. 정산 전이거나 확인할 수 없으면 null
request_breakdown결과 파일 기준 성공, 실패, 만료, 취소, 미분류, 제공자 오류의 요청 수. 확인할 수 없으면 null
billing_usage과금 근거의 모델과 토큰 등 사용량. 확인할 수 없으면 null

status 값은 다음과 같습니다.

상태뜻과 다음 행동
validating, in_progress, finalizing처리 중입니다. 같은 Batch ID로 나중에 다시 조회합니다
cancelling취소 요청을 처리하는 중입니다. 같은 Batch ID로 상태와 정산을 다시 확인합니다
completed처리가 끝났지만 모든 행이 성공했다는 뜻은 아닙니다. request_counts.completed와 failed로 행별 성공 수를 확인합니다
failed, cancelled, expiredBatch의 errors, 제공되는 파일과 정산 상태를 확인합니다. 처리 기간(completion_window)이 지난 작업은 expired가 될 수 있습니다

settlement_status 값은 다음과 같습니다.

상태뜻과 다음 행동
pending, queued, processing, settling정산 중입니다. settled_units가 null이어도 무료로 기록하지 말고 같은 Batch ID로 다시 조회합니다
settled정산이 끝났습니다. settled_units가 null이 아니면 그 값이 확정 비용이며, 문자열 "0"도 확정된 금액입니다. settled_units가 null이면 금액을 확인할 수 없는 상태이므로 null을 0으로 바꾸지 말고 Batch ID로 문의합니다
quarantined정산 보류 상태이며 무료나 정산 완료를 뜻하지 않습니다. 자동 조회를 멈추고 Batch ID로 문의합니다

처리, 파일 수령과 비용을 각각 확인하기

확인 항목읽을 값판단
처리 종료statuscompleted는 처리 종료이며 모든 행의 성공은 아님
성공 건수request_countscompleted와 failed 확인. null은 미확인
파일 수령 가능 여부output_file_id, error_file_id반환된 ID가 있으면 파일 내용 다운로드
비용 확정settlement_status, settled_unitssettled이고 금액이 null이 아닐 때 확정

정산 상태마다 비용을 어떻게 기록하는지, 과금 근거인 billing_usage가 무엇을 뜻하는지는 Batch의 확정 비용 확인하기에 있습니다. 상태와 정산 결과를 확인한 뒤 할 일의 전체 순서는 Batch 가이드의 상태 확인과 결과 받기에 있습니다.

시각과 이력

상태가 바뀐 시각을 나타내는 필드는 다음 7개입니다.

  • 처리: in_progress_at, finalizing_at
  • 종료: completed_at, failed_at, expired_at
  • 취소: cancelling_at, cancelled_at

시각 필드의 형식과 값은 다음과 같습니다.

필드형식과 값
created_at, expires_atUnix 초
위 상태 변경 시각 7개Unix 초. 공급사가 제공한 값이며, 공급사 값이 없어도 필드는 포함되고 값은 null
status_history[].observed_atISO 8601 문자열. 게이트웨이가 그 상태를 확인한 시각

상태 변경 시각이 null일 때는 다음 두 상황을 구분하세요.

  • 아직 완료되지 않은 작업의 completed_at처럼 그 단계에 도달하지 않아 시각이 없는 경우가 있습니다.
  • 게이트웨이가 완료 알림을 먼저 받고 공급사 시각을 아직 받지 못했다면 status: completed여도 completed_at: null일 수 있습니다. 공급사가 값을 제공하지 않는 경우에도 null이 유지될 수 있습니다.

현재 처리 단계는 status로 판단합니다. 시각이 null이라는 이유로 작업이 끝나지 않았거나 그 단계를 거치지 않았다고 단정하지 마세요.

status_history는 상태와 그 상태를 게이트웨이가 확인한 시각을 {status, observed_at} 형태로 담은 목록입니다.

예를 들어 공급사가 10:00에 완료하고 게이트웨이가 10:01에 확인했다면 두 시각은 1분 차이가 납니다. 게이트웨이가 두 번 확인하는 사이에 지나간 단계는 이력에 남지 않을 수 있습니다. 이력만으로는 실제 처리 시간이나 모든 상태 변경을 알 수 없습니다.

목록과 취소

API 키로 접근할 수 있는 작업

목록, 조회와 취소의 대상은 요청에 사용한 키가 개인 키인지 공유 키인지에 따라 다릅니다. 키 종류별 범위는 Batch 가이드의 콘솔과 API 키의 접근 범위에서 확인합니다. 콘솔 관리자 권한이 API 키의 접근 범위를 넓히지는 않습니다. 다른 스페이스의 작업에도 접근할 수 없습니다.

목록 조회와 다음 페이지

GET
https://gw.letsur.ai/v1/batches
인증Authorization: Bearer <API_KEY>

목록 조회 요청의 limit은 1~100이며 기본값은 20입니다. 다음 페이지를 조회할 때는 after 커서를 지정할 수 있습니다. 응답의 data와 has_more, last_id로 다음 페이지를 조회합니다. 목록 조회에는 metadata 검색 필터가 없습니다.

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

cURL
curl --fail-with-body "https://gw.letsur.ai/v1/batches?limit=20" \ -H "Authorization: Bearer $LETSUR_API_KEY"

취소 요청 뒤 결과 확인하기

POST
https://gw.letsur.ai/v1/batches/{batch_id}/cancel
인증Authorization: Bearer <API_KEY>

취소를 요청하면 작업은 cancelling 상태를 거칩니다. 단건 조회로 최종 결과를 확인하세요. 취소 전에 완료된 요청의 결과와 비용은 남을 수 있습니다.

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

cURL
curl --fail-with-body -X POST "https://gw.letsur.ai/v1/batches/$BATCH_ID/cancel" \ -H "Authorization: Bearer $LETSUR_API_KEY"

오류와 복구

Batch 생성 요청에서 반환되는 오류는 다음과 같습니다.

오류원인과 할 일
OVERAGE_NOT_ALLOWED (403), type: overage_not_allowed초과 유닛 사용이 허용되지 않은 스페이스입니다. 보유 유닛과 관계없이 거부되며, 유닛 구매만으로 해결되지 않습니다. 스페이스 관리자(Admin)에게 이용 조건을 확인합니다
endpoint_mismatch (400)생성 요청의 endpoint가 파일 업로드 때 검증된 경로와 다릅니다. 입력 파일의 url과 같은 endpoint로 요청합니다

다른 오류의 처리는 다음 위치에 있습니다.