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 생성
https://gw.letsur.ai/v1/batchesAuthorization: Bearer <API_KEY>Batch는 초과 유닛 사용이 허용된 스페이스에서만 생성할 수 있습니다. 허용되지 않은 스페이스에서는 보유 유닛과 관계없이 게이트웨이가 HTTP 403을 반환합니다. 유닛을 구매하는 것만으로는 이 거부가 풀리지 않습니다. 오류 응답의 코드는 오류와 복구에 있습니다.
- 제출 전 확인: 스페이스 관리자(Admin)에게 이용 조건을 확인합니다. 관리자도 확인할 수 없다면 플랫폼 내 문의 기능을 사용합니다.
- 별도 사용 한도: API 키와 구성원의 사용 한도도 적용됩니다. 사용 한도를 확인합니다.
요청 본문의 필드는 다음과 같습니다. 요청 헤더의 Idempotency-Key는 선택 항목입니다. 사용 조건은 재실행과 재시도에서 확인합니다.
| 필드 | 타입 | 요구 여부 | 설명 |
|---|---|---|---|
input_file_id | string | 필수 | Batch Files로 업로드한 파일의 ID |
endpoint | string | 필수 | /v1/chat/completions, /v1/responses, /v1/embeddings 중 모델이 지원하는 경로. 파일의 모든 행이 사용하는 API 경로 |
completion_window | string | 필수 | "24h"만 허용 |
metadata | object 또는 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 단건 조회
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_counts | total, completed, failed 요청 수. 확인할 수 없으면 null |
output_file_id, error_file_id | 게이트웨이 결과 파일 ID. 준비 전이거나 해당 파일이 없으면 null |
errors | Batch 오류 정보. 원인 확인에 사용 |
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, expired | Batch의 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로 문의합니다 |
처리, 파일 수령과 비용을 각각 확인하기
| 확인 항목 | 읽을 값 | 판단 |
|---|---|---|
| 처리 종료 | status | completed는 처리 종료이며 모든 행의 성공은 아님 |
| 성공 건수 | request_counts | completed와 failed 확인. null은 미확인 |
| 파일 수령 가능 여부 | output_file_id, error_file_id | 반환된 ID가 있으면 파일 내용 다운로드 |
| 비용 확정 | settlement_status, settled_units | settled이고 금액이 null이 아닐 때 확정 |
정산 상태마다 비용을 어떻게 기록하는지, 과금 근거인 billing_usage가 무엇을 뜻하는지는 Batch의 확정 비용 확인하기에 있습니다. 상태와 정산 결과를 확인한 뒤 할 일의 전체 순서는 Batch 가이드의 상태 확인과 결과 받기에 있습니다.
시각과 이력
상태가 바뀐 시각을 나타내는 필드는 다음 7개입니다.
- 처리:
in_progress_at,finalizing_at - 종료:
completed_at,failed_at,expired_at - 취소:
cancelling_at,cancelled_at
시각 필드의 형식과 값은 다음과 같습니다.
| 필드 | 형식과 값 |
|---|---|
created_at, expires_at | Unix 초 |
| 위 상태 변경 시각 7개 | Unix 초. 공급사가 제공한 값이며, 공급사 값이 없어도 필드는 포함되고 값은 null |
status_history[].observed_at | ISO 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 키의 접근 범위를 넓히지는 않습니다. 다른 스페이스의 작업에도 접근할 수 없습니다.
목록 조회와 다음 페이지
https://gw.letsur.ai/v1/batchesAuthorization: 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"취소 요청 뒤 결과 확인하기
https://gw.letsur.ai/v1/batches/{batch_id}/cancelAuthorization: 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로 요청합니다 |
다른 오류의 처리는 다음 위치에 있습니다.
metadata한도와 형식 오류: metadata- 요청 키 오류: 재시도 응답에 따른 행동의 표
- 오류 응답의 형식과 공통 재시도 기준: 오류 처리