Claude Batch API: รันงาน Async ลดต้นทุนครึ่งหนึ่ง

คำตอบสั้น: Claude Batch API ประมวลผลคำขอ Messages API แบบอะซิงโครนัสในราคาลด 50% ทั้งโทเคนอินพุตและเอาต์พุต คุณส่งคำขอได้สูงสุด 100,000 รายการ (หรือ 256 MB) ในครั้งเดียว จากนั้น poll จนกว่าแบตช์จะสิ้นสุด แล้วอ่านผลลัพธ์ที่จับคู่ด้วย custom_id ของคุณเอง แบตช์ส่วนใหญ่เสร็จภายในหนึ่งชั่วโมง และเพดานสูงสุดคือ 24 ชั่วโมง

ลองใช้ Apidog วันนี้

คุณมีตั๋วสนับสนุน 40,000 ใบที่ต้องจัดหมวดหมู่ หรือแค็ตตาล็อกสินค้าที่ต้องเขียนใหม่ หรือบทถอดเสียงหนึ่งเดือนที่ต้องสรุป ไม่มีอะไรเร่งด่วนเลย ทุกการเรียกเหล่านั้นยังคงคิดราคาเต็มเมื่อคุณยิงทีละครั้ง และคุณต้องเสียเวลาทั้งบ่ายคอยดูแลการ retry กับ rate limit ของคุณ

Claude Batch API มีอยู่เพื่อรองรับงานรูปแบบนี้โดยเฉพาะ คุณส่งรายการคำขอให้ Anthropic แล้วเดินจากไป กลับมาแล้วได้ไฟล์ผลลัพธ์ที่ราคาเพียงครึ่งหนึ่งของที่การเรียกแบบซิงโครนัสแบบเดียวกันจะคิด ไม่ต้องรันคิว ไม่ต้องปรับ concurrency ไม่ต้องมี logic สำหรับ backoff

คู่มือนี้ครอบคลุมว่า batch endpoint ทำอะไรได้บ้าง ค่าใช้จ่ายเท่าไร วิธีส่งงานและเก็บผลลัพธ์ และวิธีให้ coding agent ของคุณทดสอบทั้งหมดด้วย Apidog CLI ก่อนที่คุณจะชี้มันไปที่ข้อมูลจริง

Claude Batch API คืออะไร?

Claude Batch API คือ endpoint แบบอะซิงโครนัสที่ /v1/messages/batches ซึ่งรับคำขอ Messages API จำนวนมากในการส่งครั้งเดียว และคืนผลลัพธ์เมื่อการประมวลผลสิ้นสุดลง มันแลกความหน่วง (latency) กับส่วนลด 50% Anthropic เอกสารไว้ที่ batch processing

ข้อจำกัดที่คุณต้องออกแบบให้สอดคล้อง:

• ขนาด: สูงสุด 100,000 คำขอ หรือ 256 MB ต่อแบตช์ แล้วแต่ว่าจะถึงอันไหนก่อน
• จังหวะเวลา: แบตช์ส่วนใหญ่เสร็จภายในหนึ่งชั่วโมง 24 ชั่วโมงคือระยะเวลาสูงสุดก่อนที่คำขอที่ยังไม่เสร็จจะหมดอายุ
• การเก็บรักษา: ผลลัพธ์ยังใช้งานได้ 29 วันหลังจากสร้างแบตช์
• ฟีเจอร์เทียบเท่า: vision, การใช้ tools, system prompt และ prompt caching ทั้งหมดใช้งานได้ในแบตช์
• ลำดับ: ผลลัพธ์กลับมาในลำดับใดก็ได้ ดังนั้นคุณต้องจับคู่ด้วย custom_id ไม่ใช่ด้วยตำแหน่ง

ประเด็นสุดท้ายคือจุดที่ทำคนเจ็บ แบตช์คือถุง ไม่ใช่คิว

Claude Batch API มีค่าใช้จ่ายเท่าไร

ส่วนลดคือ 50% แบบคงที่ทั้งโทเคนอินพุตและเอาต์พุต ใช้กับโมเดลใดก็ตามที่แต่ละคำขอระบุ คุณสามารถผสมโมเดลในแบตช์เดียวได้ ดังนั้น classifier ราคาถูกและ summarizer ราคาแพงสามารถไปด้วยกันได้

อ่านแถวของ Haiku ให้ดี Haiku 5.5 คิดราคาตามขนาด prompt ดังนั้น prompt เดียวที่เกิน 100,000 โทเคนจะคิดราคา 5 เท่าของอัตรา prompt สั้น ไม่ว่าจะมีส่วนลดแบตช์หรือไม่ ประเมินงาน Haiku ที่มี context ยาวที่ $0.25 / $1.25 ไม่ใช่ $0.05 / $0.25 ตรวจสอบที่ หน้าข้อมูลราคาของ Anthropic ก่อนที่คุณจะสร้างการคาดการณ์จากตัวเลขเหล่านี้ และอ่านบทวิเคราะห์ของเราเกี่ยวกับ ค่าใช้จ่าย Claude API ไปที่ไหน ถ้าใบเรียกเก็บเงินคือเหตุผลที่คุณมาที่นี่

ราคาแบบแบตช์ยังใช้ร่วมกับ prompt caching ได้ด้วย ซึ่งเป็นที่ที่เงินออมจริงอยู่ รายละเอียดเพิ่มเติมด้านล่าง

ส่งแบตช์แรกของคุณ

ติดตั้ง Python SDK อย่างเป็นทางการ แล้วสร้างรายการคำขอ แต่ละรายการมี custom_id ที่คุณเลือก และออบเจ็กต์ params ที่ดูเหมือนการเรียก messages.create() ปกติทุกประการ

import anthropic
from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request

client = anthropic.Anthropic()

tickets = [
    "Card declined three times, support chat timed out.",
    "Love the new dashboard, the export button is hidden though.",
    "Webhook stopped firing after the 2.4 upgrade.",
]

batch = client.messages.batches.create(
    requests=[
        Request(
            custom_id=f"ticket-{i}",
            params=MessageCreateParamsNonStreaming(
                model="claude-haiku-5-5",
                max_tokens=1024,
                output_config={"effort": "low"},
                messages=[{
                    "role": "user",
                    "content": f"Label this ticket billing, bug, or praise. One word.\n\n{text}",
                }],
            ),
        )
        for i, text in enumerate(tickets)
    ]
)

print(batch.id, batch.processing_status)

ให้ custom_id มีความหมาย เช่น primary key ของฐานข้อมูลหรือ path ของไฟล์ จะช่วยให้คุณไม่ต้อง join ทีหลัง และมันคือสิ่งเดียวที่เชื่อมผลลัพธ์กลับไปยังอินพุตของมัน

ถ้าคุณชอบ HTTP ดิบ payload เดียวกันก็ส่งไปที่ POST https://api.anthropic.com/v1/messages/batches พร้อมเฮดเดอร์ x-api-key และ anthropic-version ของคุณ เอกสาร create a message batch reference มี schema แบบเต็ม

Poll แบตช์และเก็บผลลัพธ์

ดึงข้อมูลแบตช์ซ้ำจนกว่า processing_status จะอ่านว่า ended แล้วสตรีมผลลัพธ์ แต่ละผลลัพธ์มี custom_id ที่คุณตั้งไว้ และ result.type เป็น succeeded, errored, canceled หรือ expired

import time

while True:
    batch = client.messages.batches.retrieve(batch.id)
    if batch.processing_status == "ended":
        break
    print("still working:", batch.request_counts.processing)
    time.sleep(30)

labels, retry = {}, []
for result in client.messages.batches.results(batch.id):
    if result.result.type == "succeeded":
        msg = result.result.message
        labels[result.custom_id] = next(b.text for b in msg.content if b.type == "text")
    elif result.result.type == "errored":
        retry.append(result.custom_id)

print(f"{len(labels)} labeled, {len(retry)} need another pass")

โหมดความล้มเหลวสองแบบควรได้รับการจัดการแยกกัน ข้อผิดพลาด invalid_request หมายความว่าเนื้อหาคำขอผิด คุณจึงต้องแก้ไขก่อนส่งใหม่ สิ่งอื่นๆ เป็นฝั่งเซิร์ฟเวอร์และปลอดภัยที่จะ retry ตามเดิม ผลลัพธ์ expired หมายความว่าหน้าต่าง 24 ชั่วโมงปิดลงก่อนที่คำขอนั้นจะได้รัน และคุณก็ส่งคำขอเหล่านั้นใหม่เช่นกัน

Poll ด้วยตัวจับเวลา 30 ถึง 60 วินาที การกระหน่ำ retrieve endpoint ทุกวินาทีไม่ได้อะไรเลยและนับรวมกับ rate limit ของ Claude API ของคุณด้วย

ใช้ราคาแบบแบตช์ร่วมกับ prompt caching

กำไรสูงสุดมาจากการรวมส่วนลดทั้งสองเข้าด้วยกัน ถ้าทุกคำขอในแบตช์ของคุณใช้คำนำหน้า (prefix) ยาวๆ ร่วมกัน เช่น style guide, taxonomy, สัญญา 40 หน้า ให้ทำเครื่องหมาย prefix นั้นด้วย cache_control และส่ง prefix ที่ทำเครื่องหมายไว้เหมือนกันในคำขอทั้ง 10,000 รายการ

shared_system = [
    {"type": "text", "text": "You are a support triage analyst."},
    {
        "type": "text",
        "text": taxonomy_document,          # thousands of tokens, identical every time
        "cache_control": {"type": "ephemeral"},
    },
]

ใส่บล็อก system นั้นในทุก Request ในแบตช์ คำขอใดก็ตามที่มี prefix ตรงกับรายการ cache ที่ยังมีชีวิตอยู่แบบไบต์ต่อไบต์ จะคิดราคา prefix นั้นในอัตรา cache-read และส่วนลดแบตช์ 50% ก็ใช้กับทั้ง cache read และ write อย่าคาดหวังอัตราการเข้าเป้าแบบสมบูรณ์: แบตช์ประมวลผลคำขอแบบพร้อมกัน (concurrent) ไม่ได้เรียงตามลำดับ ดังนั้น cache hit ภายในแบตช์เดียวจึงเป็นแบบ best-effort คู่มือ prompt caching ของ Anthropic ครอบคลุมกฎเรื่อง prefix: ไบต์ใดก็ตามที่เปลี่ยนไปก่อนจุดตัดของคุณ จะทำให้ทุกอย่างหลังจากนั้นใช้ไม่ได้ ดังนั้นให้วาง timestamp และข้อความเฉพาะรายการไว้หลังบล็อกที่ cache ไว้

ให้ Claude Code ทดสอบ endpoint ด้วย Apidog CLI

ก่อนคุณจะใช้เงินกับคำขอจริง 100,000 รายการ คุณอยากมี regression test สำหรับวงจรชีวิตของแบตช์: create, retrieve, results การเขียนมันด้วยมือใน GUI นั้นช้า ให้ coding agent ของคุณทำด้วย Apidog CLI แทน

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install   # pick Claude Code when prompted

จากนั้นส่ง prompt หนึ่งครั้งไปยัง Claude Code:

In Apidog project 4820193, create a test case for POST https://api.anthropic.com/v1/messages/batches
that submits two Haiku 5.5 requests with custom_id ticket-0 and ticket-1, asserts the response
has an id and processing_status, then polls GET /v1/messages/batches/{id} until processing_status
is ended. Run it against the anthropic-staging environment and summarize failures.

agent จะอ่าน schema ของ payload ตรวจสอบ JSON ของตัวเอง จากนั้นสร้างและรัน test case:

apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file batch-case.json
apidog test-case create --project 4820193 --file batch-case.json
apidog run --test-case 77214 --project 4820193 -e 992301 -r cli,json

API key ของคุณอยู่ใน environment variable ของ Apidog ดังนั้นมันจะไม่หลุดไปใน prompt หรือ repo เปลี่ยน reporter เป็น -r junit แล้วคำสั่งเดียวกันก็รันใน CI ทุกครั้งที่ merge ซึ่งคือ setup ใน คู่มือ pipeline ของ Apidog CLI ของเรา ถ้าคุณยังไม่ได้เชื่อม CLI เข้ากับ agent ของคุณ เริ่มจาก การใช้ Apidog CLI ใน Claude Code

เมื่อใดที่แบตช์เป็นตัวเลือกที่ผิด

มีบางอย่างที่ไม่สามารถใช้ข้ามได้เช่นกัน Fast mode ไม่พร้อมใช้บน Batch API, server-side refusal fallback ถูกปฏิเสธที่นั่น และบน Claude Opus 5.5 และ Claude Sonnet 5.5 การบังคับ tool_choice เป็น any หรือ tool จะคืนค่า 400 ภายในแบตช์เหมือนกับการเรียกปกติทุกประการ ให้ใช้ tool_choice: auto ร่วมกับ strict: true แทน

ถ้าคุณรันโครงสร้างพื้นฐานแบบหลายผู้ให้บริการ รูปแบบเดียวกันก็มีอยู่ที่อื่นด้วย: ดู OpenAI Batch API และ Gemini API batch mode รูปร่างต่างกัน แต่เศรษฐศาสตร์ไม่ต่าง

คำถามที่พบบ่อย

Claude Batch API คืออะไร?

มันคือ endpoint แบบอะซิงโครนัสที่รันคำขอ Messages API มาตรฐานเป็นกลุ่มก้อนในราคา 50% ของราคาโทเคนปกติ คุณส่งรายการคำขอพร้อม ID ของคุณเอง, poll จนกว่าแบตช์จะจบ และอ่านผลลัพธ์ภายใน 29 วัน

Claude Batch API มีค่าใช้จ่ายเท่าไร?

ครึ่งหนึ่งของอัตรามาตรฐานทั้งอินพุตและเอาต์พุต บน Claude Sonnet 5.5 นั่นคือ $1.00 ต่อโทเคนอินพุตหนึ่งล้าน และ $5.00 ต่อโทเคนเอาต์พุตหนึ่งล้าน เทียบกับ $2.00 และ $10.00 แบบซิงโครนัส

แบตช์ของ Claude ใช้เวลานานแค่ไหน?

แบตช์ส่วนใหญ่เสร็จภายในหนึ่งชั่วโมง ระยะเวลาสูงสุดคือ 24 ชั่วโมง หลังจากนั้นคำขอที่ยังไม่ถูกประมวลผลจะคืนผลลัพธ์ expired และคุณต้องส่งใหม่

ฉันใช้ prompt caching ภายในแบตช์ได้ไหม?

ได้ และส่วนลดใช้ร่วมกันได้ ให้ทำเครื่องหมาย prefix ที่ใช้ร่วมกันด้วย cache_control ส่ง prefix ที่เหมือนกันนั้นซ้ำในทุกคำขอ และ cache read จะคิดราคาเป็นเศษเสี้ยวของราคาอินพุตบนส่วนลดแบตช์อีกชั้น

เกิดอะไรขึ้นเมื่อคำขอหนึ่งในแบตช์ล้มเหลว?

มีแค่คำขอนั้นที่ล้มเหลว ผลลัพธ์ของมันจะมาพร้อม type: "errored" พร้อมออบเจ็กต์ error ส่วนที่เหลือยังสำเร็จตามปกติ ข้อผิดพลาดจากการตรวจสอบ (validation error) ต้องแก้ payload ส่วนข้อผิดพลาดฝั่งเซิร์ฟเวอร์ปลอดภัยที่จะ retry ตามเดิม

ฉันยกเลิกแบตช์ที่กำลังรันอยู่ได้ไหม?

ได้ client.messages.batches.cancel(batch_id) จะย้ายแบตช์ไปเป็นสถานะ canceling คำขอที่เสร็จแล้วจะเก็บผลลัพธ์ไว้ ส่วนที่เหลือจะกลับมาเป็น canceled

Batch API รองรับ tools และรูปภาพไหม?

ได้ ทุกฟีเจอร์ของ Messages API ทำงานได้ในแบตช์ รวมถึง vision, นิยามของ tool และ system prompt ข้อยกเว้นคือ fast mode, server-side fallback และการบังคับ tool choice บนโมเดลตระกูล 5.5

สรุป

การประมวลผลแบบแบตช์คือการประหยัดฟรีที่ใหญ่เป็นอันดับสองบน Claude API รองจาก prompt caching และไม่ต้องแลกกับคุณภาพเลย: โมเดลเดียวกัน ฟีเจอร์เดียวกัน ครึ่งราคา โดยแลกกับความหน่วงที่คุณคงไม่ได้ใช้อยู่แล้ว ให้จับคู่ผลลัพธ์ด้วย custom_id cache prefix ที่ใช้ร่วมกัน และจัดการ expired เหมือนการ retry ไม่ใช่ความล้มเหลว

ทดสอบวงจรชีวิตก่อนที่คุณจะขยายขนาด ติดตั้ง Apidog CLI ชี้ coding agent ของคุณไปที่ batch endpoint และให้ test case ที่สร้างขึ้นรันใน CI ต่อไป เพื่อที่การเปลี่ยนแปลง schema จะไม่ทำให้คุณประหลาดใจที่คำขา 100,000 รายการ แผนฟรีครอบคลุม 4 ผู้ใช้ และคุณสามารถ ดาวน์โหลด Apidog แล้วมี test case แรกที่รันได้ในไม่กี่นาที