Batches

입력 파일로 Batch 작업을 만들고, 처리 상태와 비용을 조회하거나 작업을 취소하세요.

초과 유닛 사용이 허용된 스페이스에서 Batch를 생성할 수 있습니다.

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

AUTHAuthorization: Bearer <API_KEY>

요청 경로와 인증

Batch는 입력 파일의 요청 묶음을 실행하는 작업입니다. 파일 ID로 생성하고, 반환된 Batch ID로 조회합니다.

Base URL은 https://gw.letsur.ai입니다. AI 게이트웨이 API 키를 Bearer 헤더로 전달합니다.

동작	메서드와 경로
생성	`POST /v1/batches`
목록	`GET /v1/batches`
단건 조회	`GET /v1/batches/{batch_id}`
취소 요청	`POST /v1/batches/{batch_id}/cancel`

Batch ID는 생성 응답의 id입니다. 영상 생성의 /v1/jobs ID나 공급사의 원본 ID를 대신 사용하지 않습니다.

생성 본문

초과 유닛 사용이 허용된 스페이스에서만 생성할 수 있습니다.

제출 전 확인: 스페이스 관리자(Admin)에게 이용 조건을 확인합니다. 관리자도 확인할 수 없다면 플랫폼 내 문의 기능을 사용합니다.
허용되지 않은 경우: 보유 유닛과 관계없이 403 OVERAGE_NOT_ALLOWED로 거부됩니다. 유닛 구매만으로 해결되지 않습니다.
별도 사용 한도: API 키와 구성원의 사용 한도도 적용됩니다. 비용과 한도 안내를 확인합니다.

필드	형식	조건
`input_file_id`	string	Batch Files에서 업로드한 파일 ID. 필수
`endpoint`	string	파일의 모든 행이 사용하는 API 경로. 필수
`completion_window`	string	`"24h"`만 허용. 필수
`metadata`	object 또는 null	선택. 키와 값은 문자열


{
  "input_file_id": "FILE_ID",
  "endpoint": "/v1/chat/completions",
  "completion_window": "24h",
  "metadata": {"task": "classification"}
}

FILE_ID는 업로드 응답으로 바꿔야 하는 자리표시자입니다. endpoint는 /v1/chat/completions, /v1/responses, /v1/embeddings 중 모델이 지원하는 경로를 사용합니다. 파일에서 검증받은 경로와 달라지면 400 endpoint_mismatch입니다. 업로드 후 모델 지원 정책이 바뀌면 제출에서 다시 거부될 수 있습니다.

입력 파일의 body에 넣는 출력 상한은 모델과 API마다 다릅니다. 실시간 호출의 본문을 옮기기 전에 Batch 출력 상한 필드와 검증 범위를 확인하세요.

24h는 처리 창이며 정확한 완료 시각이나 성공을 보장하지 않습니다. 만료된 작업은 expired가 될 수 있습니다.

재실행과 재시도

하려는 일	요청 키	결과
응답이 유실된 원래 제출 확인	같은 키와 같은 본문, 24시간 계약 안	저장된 최초 제출 결과 반환
같은 입력 또는 수정한 입력으로 새 실행	새 키	새 작업과 비용 발생 가능
키 없이 제출	`Idempotency-Key` 생략	제출할 때마다 새 Batch 생성

같은 파일을 다시 사용해도 실행 중복은 막지 못합니다. Idempotency-Key는 선택 헤더이며 SDK가 자동으로 넣어준다고 가정하지 마세요.

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

범위: 같은 스페이스와 같은 소유 주체. 개인 키는 사람, 공유 키는 해당 키 자체가 소유 주체입니다. 다른 주체의 작업을 조회하는 수단이 아닙니다.
요청: 원래 키, 파일 ID, endpoint, 처리 창과 metadata를 그대로 유지합니다. 성공 응답의 Batch ID로 이후 상태를 조회합니다.
기한: 24시간을 넘긴 재시도는 중복 방지를 보장하지 않습니다. 원래 결과를 모르면 재제출 전에 작업 목록을 확인하고, 판별되지 않으면 요청 시각과 모델을 준비해 플랫폼 내 문의 기능으로 지원을 요청합니다.

재시도 응답에 따른 행동

받은 응답	다음 행동
`409 idempotency_in_flight`	결과 미확정. 기다렸다가 같은 키와 본문으로 재시도
`409 idempotency_conflict`	본문 불일치. 원래 제출을 확인하려면 원래 본문으로 되돌림
`400 idempotency_key_invalid`	빈 문자열 또는 공백뿐인 키. 유효한 키 지정. 헤더를 생략하면 새 Batch 생성
저장된 공급사 제출 실패	원인 확인 후 수정한 입력으로 새로 실행할 때 새 키 사용

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

예를 들어 classification-001의 응답이 유실됐다면 같은 키와 본문으로 확인합니다. 입력을 고쳐 새로 실행하려는 경우에만 classification-002처럼 새 키를 사용합니다. 진행 중이거나 응답이 없다는 이유로 키를 바꾸면 별도 실행이 될 수 있습니다.

metadata

고객 metadata는 응답으로 돌아오며 공급사 Batch 객체에도 전달됩니다. 이것이 고객에게 공급사 계정이나 대시보드 접근을 제공한다는 뜻은 아닙니다.

조건	한도 또는 오류
고객 키와 값 쌍	최대 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입니다. 같은 명시 키와 본문의 기존 요청을 반환하는 경우에는 새 한도 검사와 구분됩니다. metadata를 바꾸어 재시도하면 본문 충돌입니다.

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

응답 읽기

생성, 조회와 취소는 Batch 객체를 반환합니다. 자주 사용하는 필드는 다음과 같습니다.

필드	의미
`id`, `input_file_id`, `endpoint`	작업, 입력 파일과 처리 API
`status`	`validating`, `in_progress`, `finalizing`, `completed`, `failed`, `expired`, `cancelling`, `cancelled`
`request_counts`	`total`, `completed`, `failed` 요청 수. 확인할 수 없으면 null
`output_file_id`, `error_file_id`	게이트웨이 결과 파일 ID. 준비 전 또는 해당 파일이 없으면 null
`errors`	Batch 오류 정보. 원인 확인에 사용
`settlement_status`	`pending`, `queued`, `processing`, `settling`, `settled`, `quarantined`
`settled_units`	정산 완료 시 확정된 유닛 금액의 문자열. 그 전 또는 확인 불가 시 null
`request_breakdown`	결과 파일 기준 성공, 실패, 만료, 취소, 미분류, 제공자 오류의 요청 수. 확인 불가 시 null
`billing_usage`	과금 근거의 모델과 토큰 등 사용량. 확인 불가 시 null

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

확인하려는 것	읽을 값	판단
처리가 끝났는가	`status`	`completed`는 처리 종료이며 모든 행의 성공은 아님
몇 건이 성공했는가	`request_counts`	`completed`와 `failed` 확인. `null`은 미확인
파일을 받을 수 있는가	`output_file_id`, `error_file_id`	반환된 ID가 있으면 파일 API로 다운로드
비용이 확정됐는가	`settlement_status`, `settled_units`	`settled`이고 금액이 null이 아닐 때 확정

처리 상태만 보고 조회를 멈추면 뒤늦게 준비되는 파일과 확정 금액을 놓칠 수 있습니다.

quarantined: 자동 조회를 멈추고 Batch ID로 플랫폼 내 문의 기능을 이용합니다. 정산 보류는 완료나 무료를 뜻하지 않습니다.
output_file_id: null: 전체 실패로 단정하지 않습니다. 작업 상태, 요청 수, 정산 상태와 오류 파일을 함께 확인합니다. 실패 원인은 준비된 오류 파일에서 읽습니다.
금액 또는 요청 수가 null: 0이 아니라 미확인입니다.

Batch의 과금 근거는 billing_usage입니다. 표준 usage 필드는 제공하지 않으며, 개별 결과 행의 response.body.usage와 구분합니다. settling 또는 settled인데 billing_usage가 null이면 과금 근거를 확인할 수 없는 상태이므로 문의합니다.

시각과 이력

created_at, expires_at과 다음 전이 시각은 Unix 초 단위입니다.

in_progress_at, finalizing_at, completed_at, failed_at, expired_at, cancelling_at, cancelled_at

전이 시각 7개는 공급사 값을 사용합니다. 값이 없을 때도 필드는 존재하며 null을 반환합니다. 다음 두 상황을 구분하세요.

아직 완료되지 않은 작업의 completed_at처럼 해당 단계에 도달하지 않아 시각이 없는 경우가 있습니다.
status: completed여도 완료 알림을 먼저 받고 공급사 시각은 아직 확보하지 못해 completed_at: null일 수 있습니다. 공급사가 값을 제공하지 않는 경우에도 null로 남을 수 있습니다.

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

status_history는 게이트웨이가 상태를 확인한 시각인 {status, observed_at} 목록입니다. observed_at은 앞의 전이 시각과 달리 Unix 초가 아닌 ISO 8601 문자열입니다. 예를 들어 공급사가 10:00에 완료하고 게이트웨이가 10:01에 확인했다면 두 시각은 1분 차이가 납니다. 두 번의 확인 사이에 지나간 단계는 이력에 없을 수 있어, 이력만으로 실제 처리 시간이나 모든 상태 전이를 복원하지 않습니다.

목록과 취소

목록은 limit 1~100(기본 20)과 after 커서를 받습니다. 응답의 data와 has_more, last_id를 사용해 다음 페이지를 조회합니다. metadata 검색 필터는 제공하지 않습니다.

취소는 요청한 뒤 cancelling을 거쳐 최종 결과를 확인해야 합니다. 취소 전에 완료된 요청은 결과와 비용이 남을 수 있습니다. 다른 스페이스의 작업에 접근할 수 없으며 콘솔 관리자 권한이 API 키로 접근할 수 있는 작업 범위를 대신하지 않습니다.