TokenLab

파일 및 배치

메시지 배치 생성

비동기적으로 실행되는 메시지 요청 배치를 생성합니다.

POST
/v1/messages/batches

개요

한 번의 호출로 최대 100,000개의 메시지 요청을 전송합니다. 배치는 비동기적으로 실행됩니다. 응답은 즉시 반환되며 processing_status는 in_progress로 설정됩니다. 상태가 ended가 될 때까지 배치를 조회한 다음, 결과를 가져오십시오.

참고 사항

  • requests의 각 항목에는 custom_id와 params가 포함됩니다. params는 max_tokens를 포함하여 메시지 생성과 동일한 필드를 사용합니다. 항목에 speed: "fast"를 사용할 수 없습니다.
  • custom_id는 1~64자의 문자, 숫자, 밑줄 또는 하이픈으로 구성되어야 하며 배치 내에서 고유해야 합니다.
  • 배치 내의 모든 모델은 배치 처리가 가능해야 합니다. 모델이 배치 처리를 지원하지 않거나, 배치 내의 모든 모델을 처리할 수 있는 단일 경로가 없는 경우 TokenLab은 전체 요청을 400 오류로 거부합니다.
  • TokenLab은 배치를 수락할 때 예상 비용을 예약하며, 잔액이 부족할 경우 402를 반환합니다. 배치가 종료된 후 TokenLab은 성공한 요청에 대한 사용량을 정산합니다. 배치 가격은 동기식 요청 가격과 다를 수 있습니다.
  • 항목이 file_id 콘텐츠를 참조하는 경우 anthropic-beta: files-api-2025-04-14를 전송하십시오.
  • 시간 초과된 생성 요청을 안전하게 재시도하려면 Idempotency-Key를 전송하십시오. 멱등성 키를 사용한 안전한 재시도를 참조하십시오.

예시

요청

cURL
curl -X POST "https://api.tokenlab.sh/v1/messages/batches" \
  -H "x-api-key: sk-your-api-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "Idempotency-Key: 6f1c2a9e-0b7d-4c1e-9a53-2d9f3a1b7c10" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      {
        "custom_id": "request-1",
        "params": {
          "model": "claude-sonnet-5",
          "max_tokens": 1024,
          "messages": [{"role": "user", "content": "Hello, Claude!"}]
        }
      },
      {
        "custom_id": "request-2",
        "params": {
          "model": "claude-sonnet-5",
          "max_tokens": 1024,
          "messages": [{"role": "user", "content": "Name three colors."}]
        }
      }
    ]
  }'

응답 예시

응답

200 OK
{
  "id": "msgbatch_01ABC123",
  "type": "message_batch",
  "processing_status": "in_progress",
  "request_counts": {
    "processing": 2,
    "succeeded": 0,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  },
  "ended_at": null,
  "created_at": "2026-11-01T10:00:00Z",
  "expires_at": "2026-11-02T10:00:00Z",
  "cancel_initiated_at": null,
  "archived_at": null,
  "results_url": null
}

주요 필드

idstring
메시지 배치 ID입니다. 배치를 조회, 취소, 삭제하거나 결과를 가져올 때 사용합니다.
processing_statusstring
in_progress, canceling 또는 ended입니다.
request_countsobject
processing, succeeded, errored, canceled 또는 expired 상태인 요청의 수입니다.
expires_atstring
배치 만료 시간입니다. 이때까지 완료되지 않은 요청은 expired 상태로 종료됩니다.
results_urlstring|null
결과 URL입니다. 배치가 종료될 때까지 null입니다.

인증

BearerAuth
AuthorizationBearer <token>

API 키 인증입니다. Dashboard > API > API Keys에서 API 키를 생성하거나 관리하십시오.

위치: header

헤더

X-TokenLab-Delivery-Policy?string

요청별 전송 정책입니다. API 키 및 Workspace 기본값을 재정의합니다. 자동으로 TokenLab Verified를 먼저 시도하며, 출력, 요청 수락 또는 영구 리소스 생성 전에 Official 전용으로 한 번 전환될 수 있습니다.

허용 값

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

생성 요청을 안전하게 재시도할 수 있게 하는 선택적 키입니다. 각 작업마다 UUID와 같은 새로운 고유 값을 전송하십시오. 동일한 키와 동일한 본문으로 재시도하면 원래 생성 요청의 결과(일반적으로 원래 작업)가 반환되며, 두 번째 작업이 생성, 발송 또는 청구되지 않습니다. 이미 수락된 키와 다른 본문을 전송하면 409 오류가 발생합니다. 255자를 초과하는 키는 무시되며, 해당 요청은 멱등성 보호를 받지 못합니다. 멱등성 키를 사용한 안전한 재시도를 참조하십시오.

길이1 <= length <= 255

요청 본문

application/json

응답

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json