여러 요청을 Batch로 처리하기
여러 요청을 파일로 제출하고 결과 받기
초과 사용이 허용된 스페이스에서 JSONL 입력을 준비해 Batch를 제출하고, 결과 파일과 정산을 각각 확인하는 순서 및 재시도 조건을 안내합니다.
페이지 목차
파일과 작업을 구별하기
즉시 응답이 필요하지 않은 요청이 여러 개라면 JSONL 파일로 묶어 Batch 작업으로 제출하고 대량으로 처리할 수 있습니다. 제출한 요청은 비동기로 처리됩니다. 처리가 끝나면 결과 파일을 받아 요청별 결과를 확인합니다. 즉시 응답이 필요하다면 첫 API 호출 안내에 따라 요청을 보내세요. 제품 화면에서는 이 기능을 배치 관리라고 부릅니다.
현재 상황에 맞는 절에서 시작하세요.
| 지금 가진 것 | 다음 행동 |
|---|---|
| Batch를 처음 실행함 | 시작 조건과 입력을 확인하고 한 줄로 시험 |
| 입력 파일 ID만 있음 | 반환된 파일 ID로 Batch 제출 |
| 이미 Batch ID가 있음 | AI 게이트웨이 > 배치 관리의 배치 작업 탭에서 조회 범위 확인, 또는 같은 ID로 처리 상태, 결과 파일과 정산을 API에서 확인 |
| 업로드 또는 제출 응답을 받지 못함 | 응답을 받지 못한 단계를 먼저 확인 |
Batch는 다음 순서로 진행합니다.
- 파일 업로드: API로 요청합니다.
- Batch 생성: API로 요청합니다.
- 상태 조회: API로 조회하거나 배치 관리 화면에서 진행 상태를 확인합니다.
- 결과 파일 다운로드: API나 배치 관리 화면에서 받습니다.
파일과 작업은 서로 다른 API가 다룹니다. 업로드 응답의 파일 ID와 실행 작업의 Batch ID를 각각 기록하세요.
| API | 다루는 것 | 기록할 ID |
|---|---|---|
| Batch Files | 입력, 결과 및 오류 파일. 업로드만으로 작업이 실행되지는 않습니다 | 업로드 응답의 파일 ID |
| Batches | 업로드한 파일 ID로 만드는 실행 작업. 반환된 Batch ID로 상태와 결과 파일 ID를 조회합니다 | 생성 응답의 Batch ID |
시작 전 준비
- 초과 사용이 허용된 스페이스
보유 유닛이나 유닛 구매만으로는 이 조건이 충족되지 않습니다. AI 게이트웨이 > 배치 관리에서 제출 가능 안내를 확인하세요. 안내가 없거나 상태를 확인할 수 없다면 스페이스 관리자(Admin)에게 확인을 요청합니다. Admin은 서버에서 관리 API 키로 유닛 잔액 조회를 요청해 응답의
overage.allowed필드에서 초과 사용 허용 여부를 확인할 수 있습니다. 초과 사용 허용이 필요하거나 값을 확인할 수 없다면 로그인한 뒤 플랫폼 내 문의 기능으로 요청합니다. - AI 게이트웨이 API 키
현재 사용할 수 있는 AI 게이트웨이 API 키를 준비합니다.
- Batch를 지원하는 모델
배치 관리 > 지원 모델 탭 또는 Models API의
supports_batch에서 지원 모델을 확인합니다. 모델이 목록에 있거나supports_batch가true여도 모든 입력을 제출할 수 있다는 뜻은 아닙니다. Batch Files의 API별 입력 조건과 모델별 입력 조건도 확인합니다. - 모델의 입력 조건
에셋에서 지원 API와 입력 한도를 확인합니다. 실시간 API 지원만으로 Batch 지원을 판단하지 않습니다.
예제는 Python과 OpenAI SDK로 작성했습니다. 실시간 호출에서 성공한 본문이라도 입력 한 줄로 먼저 Batch를 실행해 결과까지 확인한 다음 요청 수를 늘리세요. 한 줄 시험에도 사용량에 따른 비용이 발생합니다.
입력 파일 만들기
input.jsonl 파일에 요청마다 JSON 객체 한 줄을 작성합니다. 아래 세 예제 가운데 사용할 API에 맞는 예제 하나로 시작하세요. 예제에 쓴 모델의 지원 여부와 입력 조건도 Models API와 에셋에서 확인합니다.
파일을 만들 때는 다음 규칙을 지킵니다.
- 한 파일에는 같은 모델과 같은 endpoint의 요청만 넣습니다.
- 각 행의
custom_id값은 파일 안에서 겹치지 않아야 합니다. 원래 요청과 결과는 결과 순서 대신 이 값으로 연결합니다.
Chat Completions
다음은 예시 모델 gpt-4o-mini로 보내는 Chat Completions 요청입니다. 다른 모델에서는 모델별 입력 조건을 확인합니다.
{"custom_id":"request-1","method":"POST","url":"/v1/chat/completions","body":{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Batch 처리를 한 문장으로 설명해 주세요."}],"service_tier":"default"}}파일을 업로드하면 게이트웨이가 입력 행을 검증합니다. 실시간 호출에서 성공한 본문도 Batch에서는 거부되거나 처리 중에 실패할 수 있으니, 업로드하기 전에 다음 조건을 확인하세요.
| 확인할 조건 | 확인할 곳 |
|---|---|
API별 service_tier와 출력 상한 필드, Batch에서 쓸 수 없는 필드 | API별 입력 조건 |
| 모델에 따라 다른 출력 상한 필드와 도구 조건 | 모델별 입력 조건 |
| 파일 크기와 행 수 제한 | Batch Files |
조건을 확인했더라도 한 줄 시험을 먼저 거치세요. 긴 입력은 업로드를 통과한 뒤에도 실패할 수 있으니 긴 입력의 한 줄 시험도 확인합니다.
업로드하고 제출하기
입력 파일을 업로드해 파일 ID를 받은 뒤, 그 파일 ID로 Batch 작업을 제출합니다. 업로드와 제출에는 서로 다른 요청 키를 사용합니다.
실행 환경과 예제 파일 준비
패키지를 설치할 수 있는 Python 3.8 이상 환경에 SDK를 설치합니다. 가상 환경 사용을 권장합니다. 아래 python3 명령은 선택한 가상 환경의 Python으로 실행합니다. 환경 변수 LETSUR_API_KEY에 키가 없으면 예제는 실행 중에 키를 입력받으며, 입력한 키는 화면에 표시하지 않습니다.
python3 -m pip install openai다음 코드를 batch_example.py로 저장합니다. 이 코드는 SDK 클라이언트에 게이트웨이 주소를 지정하고 자동 재시도를 끕니다. 제출 응답을 받지 못했다면 파일 ID, 본문, 요청 키를 모두 그대로 두고 직접 다시 보냅니다.
batch_example.py 전체 코드
import json
import os
import sys
from getpass import getpass
from pathlib import Path
from openai import OpenAI
def main():
client = OpenAI(
api_key=os.environ.get("LETSUR_API_KEY") or getpass("AI 게이트웨이 API 키: "),
base_url="https://gw.letsur.ai/v1",
max_retries=0,
)
action = sys.argv[1]
if action == "upload":
with open(sys.argv[2], "rb") as source:
print(client.files.create(
file=source, purpose="batch",
extra_headers={"Idempotency-Key": sys.argv[3]},
).id)
elif action == "submit":
job = client.batches.create(
input_file_id=sys.argv[2],
endpoint=sys.argv[3],
completion_window="24h",
extra_headers={"Idempotency-Key": sys.argv[4]},
)
print(job.id)
elif action in {"status", "download"}:
job = client.batches.retrieve(sys.argv[2])
data = job.model_dump()
print(json.dumps(data, ensure_ascii=False, indent=2))
if action == "status":
return
settlement = data.get("settlement_status")
if settlement == "quarantined":
print("정산이 보류됐습니다. Batch ID로 지원을 요청하세요.")
elif settlement != "settled":
print("비용은 미확정입니다. 같은 Batch ID로 나중에 조회하세요.")
elif data.get("settled_units") is None:
print("확정 비용을 확인할 수 없습니다. Batch ID로 지원을 요청하세요.")
if not any(data.get(field) for field in ("output_file_id", "error_file_id")):
raise SystemExit("받을 파일 ID가 없습니다. 작업 및 정산 상태와 errors를 확인하고, 처리 중이면 같은 Batch ID로 다시 조회하세요.")
for field, suffix in [("output_file_id", "output"), ("error_file_id", "error")]:
if file_id := data.get(field):
target = Path(f"{job.id}-{suffix}.jsonl")
content = client.files.content(file_id).content
with target.open("xb") as output:
output.write(content)
print(f"저장: {target}")
elif action == "cancel":
print(client.batches.cancel(sys.argv[2]).model_dump_json())
else:
raise SystemExit("upload / submit / status / download / cancel 중 하나를 사용하세요.")
if __name__ == "__main__":
main()1. 입력 파일 업로드
위의 전체 코드를 펼쳐 batch_example.py로 저장하고, 앞에서 준비한 input.jsonl과 같은 디렉터리에서 실행합니다. 아래 명령은 입력 파일 업로드 API를 호출하고 파일 ID를 출력합니다. 출력된 파일 ID를 기록하세요. 명령의 my-input-upload-001 부분은 이 업로드에 쓸 고유 요청 키의 예입니다.
업로드한 뒤 Batch를 제출하지 않거나 제출이 거부되더라도 이미 이루어진 파일 전달은 취소되지 않습니다. 제출 조건과 파일 내용을 확인한 뒤 업로드하세요. 공개된 처리 업체와 이전 범위는 데이터 처리 위탁 현황에서 확인합니다.
python3 batch_example.py upload input.jsonl my-input-upload-001다시 업로드할 때는 목적에 따라 업로드 키를 다르게 씁니다.
| 하려는 일 | 업로드 키와 파일 |
|---|---|
| 응답을 받지 못해 원래 업로드를 확인 | 24시간 안에 같은 업로드 키와 한 바이트도 바꾸지 않은 같은 파일 |
| 파일을 수정해 다시 업로드 | 새 업로드 키 |
업로드 키는 같은 파일 업로드가 중복 처리되지 않게 하고, 다음 단계의 제출 키는 Batch 작업이 중복 생성되지 않게 합니다. 자세한 오류 처리는 업로드 재시도를 확인하세요.
2. Batch 작업 제출
업로드가 끝났다면 다시 업로드하지 않고 Batch 생성 API를 호출합니다. 아래 명령을 실행하려면 먼저 실행 환경과 예제 파일을 준비합니다.
명령의 FILE_ID 자리에 업로드에서 받은 파일 ID를 넣고, endpoint에는 JSONL의 url과 같은 값을 씁니다. 아래 명령은 Chat Completions 예제 기준입니다. 다른 예제를 골랐다면 endpoint를 다음 값으로 바꿉니다.
| 입력 파일 예제 | 제출 명령의 endpoint |
|---|---|
| Chat Completions | /v1/chat/completions |
| Responses | /v1/responses |
| Embeddings | /v1/embeddings |
명령의 my-batch-run-001 부분은 이 실행에만 쓸 고유 요청 키의 예입니다.
같은 작업이 중복 실행되고 추가 비용이 발생할 수 있습니다. 응답을 받지 못했다면 24시간이 지났더라도 다시 제출하기 전에 원래 Batch가 생성됐는지 확인하세요.
python3 batch_example.py submit FILE_ID /v1/chat/completions my-batch-run-001처리 창 completion_window에는 "24h"만 쓸 수 있고, 예제도 이 값을 지정합니다. 24시간은 요청을 처리하는 기간일 뿐 정확한 완료 시각이나 성공을 보장하지 않습니다. 이 기간이 지난 작업은 expired 상태가 될 수 있습니다.
출력된 Batch ID를 저장합니다. 다시 제출할 때는 목적에 따라 요청 키를 다르게 지정합니다.
| 하려는 일 | 요청 키와 본문 |
|---|---|
| 응답을 받지 못해 원래 제출을 확인 | 24시간 안에 같은 요청 키와 같은 본문 |
| 같은 파일을 의도적으로 다시 실행 | 새 요청 키 |
충돌 응답과 진행 중 응답의 처리 방법은 재시도 조건에서 확인하세요.
상태를 확인하고 결과 받기
Batch ID와 그 작업에 접근할 수 있는 AI 게이트웨이 API 키가 필요합니다. Batch ID는 생성 응답의 id이며 입력 파일 ID와 다릅니다. 아래 조회는 기존 작업을 확인하며 새 Batch를 제출하지 않습니다.
1. 처리 상태 확인
명령의 BATCH_ID 자리에 확인하려는 작업의 ID를 넣고, 아래 두 명령 가운데 하나만 실행합니다.
cURL 명령에는 서버 환경 변수 LETSUR_API_KEY만 있으면 됩니다. batch_example.py나 SDK는 설치하지 않아도 됩니다.
curl --fail-with-body "https://gw.letsur.ai/v1/batches/BATCH_ID" \
-H "Authorization: Bearer $LETSUR_API_KEY"실행 환경과 예제 파일 준비에서 SDK와 batch_example.py를 준비했다면 cURL 대신 다음 Python 명령을 써도 됩니다. 이미 Batch ID가 있으니 업로드와 제출 단계는 다시 실행하지 않습니다.
python3 batch_example.py status BATCH_ID두 명령 모두 한 번만 조회합니다. 응답의 status 값을 보고 다음 행동을 정하세요. 작업이 처리 중이면 간격을 두고 같은 명령을 다시 실행합니다.
| 상태 | 다음 행동 |
|---|---|
validating, in_progress, finalizing | 같은 Batch ID로 나중에 다시 조회 |
cancelling | 취소 요청이 처리되는 중이므로 같은 Batch ID로 상태와 정산을 다시 확인 |
completed | 처리 종료만 뜻하며 모든 요청의 성공이나 정산 완료는 아님. request_counts.completed와 failed로 행별 성공 수 확인. 예: total: 1, completed: 0, failed: 1이면 성공한 요청 없음 |
failed, cancelled, expired | Batch의 errors, 제공되는 파일과 정산 상태 확인 |
응답의 필드 목록은 Batches의 단건 조회에서 확인합니다.
2. 반환된 파일 받기
파일이 준비되면 바로 저장하세요. 만료된 파일은 파일 ID가 남아 있어도 다시 다운로드된다는 보장이 없습니다. 보관 조건은 파일 보관과 만료에서 확인합니다.
조회 응답에 output_file_id 또는 error_file_id 필드가 있으면 다음 방법 가운데 하나로 파일을 받습니다. 파일 ID가 없다면 파일 ID가 없을 때의 상태별 대응을 확인합니다.
- API로 받을 때: Batch Files의 파일 내용 다운로드를 호출합니다.
- 콘솔에서 받을 때: AI 게이트웨이 > 배치 관리 > 배치 작업에서 작업을 선택하고, 상세 화면에 있는 결과 파일이나 오류 파일을 다운로드합니다. 파일이 있어도 권한에 따라 다운로드하지 못할 수 있으니 콘솔의 접근 범위를 확인하세요.
- Python 예제로 받을 때: 전체 Python 예제를 준비했다면 아래 명령으로 반환된 파일을 저장합니다.
python3 batch_example.py download BATCH_ID- 성공 결과는
BATCH_ID-output.jsonl, 개별 오류는BATCH_ID-error.jsonl에 저장됩니다. 결과에 따라 한쪽만 있을 수 있습니다. - 같은 이름의 파일이 있으면 예제는 파일을 덮어쓰지 않고 중단합니다. 기존 파일을 보관하고 다른 디렉터리에서 실행하세요.
- 각 행의
custom_id로 원래 입력을 찾습니다.response.status_code와error에서 요청의 처리 결과를 확인하고, 응답 본문에 필요한 출력이 있는지도 확인합니다.
파일을 받았더라도 확정 비용은 settlement_status와 settled_units 필드로 따로 확인합니다. 방법은 3. 비용 확정 확인에 있습니다.
파일 ID가 없을 때
정산 중에는 결과 파일 ID가 비어 있을 수 있습니다. 상태가 completed가 된 직후라도 파일 ID가 준비될 때까지 같은 Batch ID로 다시 조회합니다.
| 확인한 상황 | 다음 행동 |
|---|---|
처리 중이거나 정산이 pending, queued, processing, settling | 같은 Batch ID로 다시 조회. 새 Batch를 제출하지 않음 |
정산이 quarantined | 자동 조회를 멈추고 Batch ID로 플랫폼 내 문의 |
정산이 settled인데 한쪽 ID가 없음 | 해당 종류의 결과가 없을 수 있음. 요청 수, errors와 다른 파일 ID 확인 |
| Batch 전체 제출 검증 실패 | 파일 대신 Batch 객체의 errors에서 원인 확인 |
파일 ID가 없어도 일부 요청은 처리됐을 수 있습니다. 원인을 확인할 수 없다면 지원 요청에 필요한 정보를 준비합니다.
3. 비용 확정 확인
비용은 파일 수령과 별도로 같은 Batch ID로 확인합니다. settlement_status가 settled이고 settled_units가 null이 아닐 때 settled_units가 확정 비용입니다. 그 밖의 정산 상태에서 할 일은 Batch의 확정 비용 확인하기에서 확인합니다.
실패한 요청을 고쳐 다시 실행하기
실패한 입력을 수정해 다시 제출하면 새 실행이 됩니다. 응답을 받지 못해 원래 제출을 확인하는 재시도와 다르므로 새 요청 키를 사용합니다.
- 결과 파일과 오류 파일의
custom_id를 원래 입력 파일과 대조해 다시 실행할 요청을 선택합니다. 이미 성공한 요청은 제외합니다. - 오류에 맞게 해당 요청의 본문을 수정합니다. 오류 코드가
unsupported_parameter이면 파라미터 오류의 수정 방법을 따르고,context_length_exceeded이면 입력을 줄이거나 나눕니다. - 수정한 요청 중 한 건만 포함한 시험용 JSONL 파일을 만들고 업로드해 반환된 파일 ID를 기록합니다.
- 시험 파일 ID와 새 요청 키로 제출하고 결과를 확인합니다.
- 시험이 정상 처리되면 나머지 요청을 별도 JSONL 파일로 업로드하고, 또 다른 새 요청 키로 제출합니다. 시험에 성공한 요청은 이 파일에서 뺍니다.
수정한 본문을 원래 요청 키로 보내면 409 idempotency_conflict 오류가 발생합니다.
취소하기
정산 결과는 3. 비용 확정 확인에서 확인하세요.
처리 중인 작업의 취소를 요청하려면 다음 명령을 사용합니다. 배치 관리 화면에서도 본인이 제출한 작업을 취소할 수 있으며, 역할별 범위는 콘솔과 API 키의 접근 범위에서 확인합니다.
python3 batch_example.py cancel BATCH_ID취소 요청이 성공했어도 작업 취소가 끝났다는 뜻은 아닙니다. 상태가 cancelling인 동안 기다린 뒤 상태와 정산을 다시 확인하세요. 처리 시간은 요청과 모델에 따라 다릅니다.
비용과 사용 한도 확인하기
Batch별 확정 비용은 스페이스의 누적값과 다릅니다. 누적 사용량, 잔액과 작업별 비용 기록 방법은 Batch의 확정 비용 확인하기에서 확인합니다.
초과 사용이 허용된 스페이스라도 API 키나 구성원의 사용 한도를 이미 초과했다면 신규 Batch 제출이 차단될 수 있습니다. 사용 한도에는 아직 정산되지 않은 작업의 비용이 미리 반영되지 않으므로, 한도만으로 전체 지출 상한을 보장할 수 없습니다. 자세한 내용은 월 사용 한도에서 확인합니다.
콘솔과 API 키의 접근 범위
AI 게이트웨이 > 배치 관리 > 배치 작업에서 볼 수 있는 작업과 할 수 있는 일은 역할에 따라 다릅니다.
| 작업 | Admin | Member |
|---|---|---|
| 작업 이력 확인 | 같은 스페이스의 작업 | 본인 작업 |
| 결과 파일 다운로드 | 본인 작업. Member의 작업은 유효한 개인 소유자가 연결되어 있으면 가능 | 본인 작업 |
| 작업 취소 | 본인이 제출한 작업. 다른 사람의 작업은 불가 | 본인이 제출한 작업 |
API로 접근할 때는 콘솔 관리자 권한이 적용되지 않습니다. 키가 사람에게 연결되어 있는지에 따라 접근 범위가 달라집니다.
- 개인 키
콘솔의 API 키 화면에서 만드는, 사람에게 연결된 키입니다.
- 공유 키
개인 소유자에게 연결되지 않은 키입니다.
개인 키와 공유 키는 키 값을 함께 쓰는 사람 수와 관계없이 이 기준으로 나눕니다.
| API 키 | 작업의 목록, 조회와 취소 | 파일의 조회와 다운로드 |
|---|---|---|
| 개인 키 | 같은 스페이스에서 키 소유자가 제출한 작업 | 같은 스페이스에 있는 그 소유자의 파일 |
| 공유 키 | 같은 스페이스에서 그 공유 키로 제출한 작업 | 같은 스페이스에 있는 그 키의 파일 |
다른 스페이스의 작업과 파일에는 접근할 수 없습니다. 개인 키를 교체했다면 새 키를 만든 사람과 키의 유효성, 키가 속한 스페이스의 접근 권한을 확인하세요.
키를 삭제하거나 구성원을 제거하기 전에 결과를 받을 접근 경로를 확인하세요. 키 종류나 결과를 받을 접근 경로를 알 수 없다면 플랫폼 내 문의 기능에 Batch ID와 키 이름을 남겨 먼저 확인을 요청하세요. 키 값은 보내지 마세요. 키가 노출됐다면 접근 경로 확인을 기다리지 말고 즉시 삭제와 복구 절차를 따릅니다.
문제 해결
응답을 받지 못한 단계를 먼저 구분하세요. 업로드 키와 제출 키는 별개입니다. 아래 표는 같은 스페이스에서 24시간 안에 원래 요청을 확인하는 방법입니다. 개인 키는 키를 만든 사람이 같아야 하고, 공유 키는 원래 키를 유지해야 합니다.
제출 키를 바꾸거나 빼고 다시 보내면 별도 Batch가 생성되어 추가 비용이 발생할 수 있습니다. 재시도 조건은 2. Batch 작업 제출에서 확인하세요.
| 증상 | 다음 행동 |
|---|---|
업로드에서 invalid_line | 행 번호와 사유를 확인해 모델, endpoint와 필드를 수정합니다. 사유별 조건은 Batch Files의 오류와 복구에서 확인합니다. |
제출에서 endpoint_mismatch | 입력 파일의 url과 제출 endpoint를 일치시킵니다. |
403 OVERAGE_NOT_ALLOWED | 스페이스 관리자(Admin)에게 초과 사용 허용 여부를 확인합니다. 유닛 구매로 해결되지 않습니다. 확인이 어렵다면 시작 전 준비의 문의 경로를 따릅니다. |
| 파일 또는 작업에 접근할 수 없음 | 요청에 쓴 키의 스페이스와 유효성을 확인합니다. 개인 키는 원래 키와 만든 사람이 같은지, 공유 키는 원래 키와 같은 키인지 확인합니다. 콘솔과 API 키의 접근 범위를 확인하고, 오류만 보고 파일이 있는지 없는지 단정하지 않습니다. |
429 policy_limit_exceeded | 적용된 한도와 사용량을 확인합니다. 새 요청 키로 우회하지 않습니다. |
400 idempotency_key_invalid | 요청 키가 빈 문자열이나 공백뿐인지 확인합니다. 새 요청의 잘못된 키는 유효한 값으로 고칩니다. 응답 유실 뒤 재시도라면 원래 요청의 키를 유지합니다. |
409 idempotency_conflict 또는 idempotency_in_flight | 같은 제출의 재시도와 새 실행을 구분해 재시도 응답에 따른 행동대로 처리합니다. |
| HTTP 200인데 출력이 비어 있음 | 답변 내용이 비어 있는 경우를 확인합니다. |
| 작업 완료 후 결과 파일이 없음 | 정산 상태와 errors를 먼저 확인합니다. |
| 처리 시간이 길어짐 | 같은 ID로 조회합니다. 새 Batch를 제출하면 별도 실행과 비용이 생길 수 있습니다. |
오류 응답의 형식과 공통 재시도 기준은 오류 처리에서 확인합니다.
해결되지 않으면 플랫폼 내 문의 기능에 Batch ID, 요청 시각, 사용한 모델과 endpoint, 오류 코드를 남깁니다. 파일 문제라면 파일 ID도 함께 전달합니다. API 키나 요청에 포함된 민감한 원문은 보내지 마세요.
긴 입력의 처리 후 실패
컨텍스트 한도를 넘는 요청은 업로드와 제출을 통과한 뒤 처리 중에 실패할 수 있습니다. 같은 Batch의 다른 요청이 성공했다면 성공한 요청에는 비용이 발생할 수 있습니다.
제출하기 전에 다음을 확인하세요.
- 에셋 화면에서 모델의 토큰 한도와 입력 크기를 확인합니다.
/v1/models응답의max_input_tokens필드는 지금null입니다.null은 무제한이라는 뜻이 아닙니다. - 긴 요청도 한 줄짜리 Batch로 먼저 시험합니다.
요청은 성공했는데 답변 내용이 비어 있는 경우
추론 모델은 답변을 생성하기 전에 추론에도 토큰을 사용합니다. Chat Completions의 max_completion_tokens는 추론에 쓴 토큰과 실제 답변 토큰을 합친 상한입니다. 예를 들어 상한을 500으로 지정했는데 모델이 추론에 500토큰을 모두 사용하면, 요청이 HTTP 200으로 처리돼도 답변 내용은 빈 문자열일 수 있습니다. 모델이 이미 토큰을 사용했으므로 비용이 발생할 수 있습니다.
결과 행의 response.body에서 다음을 함께 확인하세요.
choices[0].message.content: 실제 답변 내용의 유무를 확인합니다.choices[0].finish_reason:length이면 토큰 상한 때문에 답변이 끝났을 수 있습니다.usage.completion_tokens와 제공되는usage.completion_tokens_details.reasoning_tokens: 출력 예산 중 추론에 사용한 양을 확인합니다.
답변이 비어 있다면 출력 상한을 늘리거나 요청을 단순하게 바꿔 한 건으로 다시 시험합니다. 재실행에는 추가 비용이 발생할 수 있으므로 빈 답변이 있다는 이유로 전체 파일을 자동 재제출하지 마세요. 빈 답변은 파라미터 오류로 실행이 거부된 HTTP 400과 다릅니다.
파라미터 오류로 모든 행이 실패한 경우
오류 파일의 response.body.error.code가 unsupported_parameter이고 param이 max_tokens이면 max_tokens를 모델과 API에 맞는 출력 상한 필드로 고칩니다. Chat Completions 입력에서 출력 상한에 max_completion_tokens를 쓰는 모델이라면 값은 유지하고 필드 이름만 max_completion_tokens로 바꿉니다. 수정한 파일은 실패한 요청을 고쳐 다시 실행하기의 순서대로 새로 업로드하고, 새 파일 ID와 새 제출 키로 한 줄부터 시험하세요.
파라미터 오류로 모든 행이 거부돼 토큰 사용량이 0이었다면 정산 완료 뒤 확정 비용도 0인지 확인합니다.