Anthropic Batch API po polsku, 50% off na masowe zadania 2026

Spis treści

• Czym jest Batch API
• Mechanizm: submit, poll, retrieve
• Cennik (50% off)
• Kiedy używać
• Kiedy NIE używać
• Implementacja Python
• Implementacja TypeScript
• Łączenie z prompt caching
• Monitoring i error handling
• Przykład ROI
• Antywzorce
• FAQ

Aktualizacja: maj 2026. Message Batches API to drugi (obok prompt cachingu) najmocniejszy sposób redukcji kosztów Anthropic API. 50% off na input i output tokens, max 100k requestów per batch, 24h SLA. Łącząc z prompt caching dochodzisz do około 93% off łącznie. Idealne do data labeling, content generation, evaluation, classification i innych zadań gdzie latency nie ma znaczenia.

Czym jest Batch API

Message Batches API to asynchroniczny endpoint Anthropic wydany w październiku 2024. W odróżnieniu od sync API (które zwraca response natychmiast po inference), batch przyjmuje paczkę do 100 000 requestów, kolejkuje je po stronie Anthropic, i daje wyniki w ciągu 24h. Płatność: 50% bazowej ceny tokens, niezależnie od modelu (Sonnet, Opus, Haiku).

To narzędzie do masowych tasków async: klasyfikacja 10k komentarzy, generowanie dokumentacji dla 500 funkcji, evaluation 1000 promptów na różnych modelach, data labeling. Każde zadanie, gdzie potrzebujesz wielu odpowiedzi ale nie wymagasz real-time, zwraca się 2× szybciej kosztowo z Batch API.

Mechanizm: submit, poll, retrieve

Lifecycle batch ma 3 fazy:

1. Submit: tworzysz batch przez POST /v1/messages/batches z array requestów (do 100k). Każdy ma custom_id (twój identyfikator) i params (model, messages, tools itd.)
2. Poll: sprawdzasz status przez GET /v1/messages/batches/<id>. Statusy: in_progress (działa), ended (zakończony), z sub-statusami sukces/error/canceled/expired
3. Retrieve: po ended pobierasz wyniki przez GET /v1/messages/batches/<id>/results. JSONL z odpowiedzią per request

Wyniki są dostępne przez 29 dni. Po tym czasie znikają, musisz pobrać i zapisać u siebie.

Cennik: 50% off

Porównanie cen sync vs batch (Sonnet 4.6, $3 input / $15 output / MTok)

Operacja	Sync API	Batch API	Oszczędność
Input tokens	$3 / MTok	$1.50 / MTok	50%
Output tokens	$15 / MTok	$7.50 / MTok	50%
Cache write (batch)	$3.75 / MTok	$1.875 / MTok	50%
Cache read (batch)	$0.30 / MTok	$0.15 / MTok	50%

Batch + caching = bardzo mocne combo. Dla 10k requestów z tym samym system promptem (10k tokens) liczbowo: sync no-cache $300, batch no-cache $150, batch + cache $30 (przy 99% cache hit). To 10× tańsza opcja niż naive sync API.

Kiedy używać Batch API

• Classification / labeling, klasyfikacja 1k-100k tickets, komentarzy, dokumentów
• Content generation w skali, generowanie meta tags, descriptions, summaries dla całego katalogu produktów
• Evaluation, testowanie nowego promptu na 1000 reference cases (regression testing)
• Translation / localization, masowe tłumaczenia, np. cała baza znaków
• Data enrichment, dodawanie sentiment, entities, kategorii do datasetu
• Audit / extraction, parsing dokumentów (PDF, kontrakty) z całego archiwum

Kiedy NIE używać Batch API

• Real-time interakcja z userem, latency 24h niedopuszczalne
• Streaming responses, batch nie wspiera, użyj sync
• Low-volume, dla 5-10 requestów overhead setup batch nie zwraca się
• Interactive workflow, gdzie output jednego requesta wpływa na kolejny (sekwencyjna logika)
• Tight deadline, jeśli MUSISZ mieć wynik za godzinę, sync bezpieczniejszy (batch teoretycznie 24h)

Implementacja Python

Z Anthropic SDK 0.40+, tworzenie batch:

from anthropic import Anthropic

client = Anthropic()

batch = client.messages.batches.create(
    requests=[
        {
            "custom_id": f"task-{i}",
            "params": {
                "model": "claude-sonnet-4-6",
                "max_tokens": 256,
                "messages": [{"role": "user", "content": f"Sklasyfikuj: {item}"}]
            }
        }
        for i, item in enumerate(items)
    ]
)

print(f"Batch ID: {batch.id}, status: {batch.processing_status}")

Polling status:

import time

while True:
    batch = client.messages.batches.retrieve(batch.id)
    if batch.processing_status == "ended":
        break
    print(f"Status: {batch.processing_status}, "
          f"completed: {batch.request_counts.succeeded}/{batch.request_counts.processing}")
    time.sleep(60)

Pobranie wyników (JSONL stream):

for result in client.messages.batches.results(batch.id):
    if result.result.type == "succeeded":
        custom_id = result.custom_id
        message = result.result.message
        print(f"{custom_id}: {message.content[0].text}")
    elif result.result.type == "errored":
        print(f"Error for {result.custom_id}: {result.result.error}")

Implementacja TypeScript

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

// 1. Submit
const batch = await client.messages.batches.create({
  requests: items.map((item, i) => ({
    custom_id: `task-${i}`,
    params: {
      model: "claude-sonnet-4-6",
      max_tokens: 256,
      messages: [{ role: "user", content: `Sklasyfikuj: ${item}` }]
    }
  }))
});

// 2. Poll
let status = batch;
while (status.processing_status !== "ended") {
  await new Promise(r => setTimeout(r, 60000));
  status = await client.messages.batches.retrieve(batch.id);
}

// 3. Retrieve
const results = client.messages.batches.results(batch.id);
for await (const result of results) {
  if (result.result.type === "succeeded") {
    console.log(result.custom_id, result.result.message.content);
  }
}

Łączenie z prompt caching

Batch + prompt caching to najmocniejsze combo dla masowych workloadów. Pierwszy request w batch zapisuje cache (125% × 50% = 62.5% bazowej ceny). Kolejne czytają (10% × 50% = 5% bazowej ceny).

# 10 000 klasyfikacji z tym samym system promptem 10k tokens

batch = client.messages.batches.create(
    requests=[
        {
            "custom_id": f"classify-{i}",
            "params": {
                "model": "claude-sonnet-4-6",
                "max_tokens": 100,
                "system": [
                    {
                        "type": "text",
                        "text": long_classifier_prompt,
                        "cache_control": {"type": "ephemeral"}
                    }
                ],
                "messages": [{"role": "user", "content": text}]
            }
        }
        for i, text in enumerate(texts)
    ]
)

Pełen deep dive w prompt caching Anthropic po polsku.

Monitoring i error handling

W batch.request_counts znajdziesz pełen audit:

• processing, jeszcze w toku
• succeeded, zakończone sukcesem
• errored, błąd (rate limit, malformed, model error)
• canceled, anulowane przez user
• expired, przekroczone 24h (rzadkie)

Best practice retry logic:

failed = [r for r in results if r.result.type == "errored"]
if failed:
    # Retry failed requests w nowym batch
    retry_batch = client.messages.batches.create(
        requests=[
            {"custom_id": f["custom_id"], "params": original_params[f["custom_id"]]}
            for f in failed
        ]
    )

Przykład ROI: 10k klasyfikacji

Realistyczny scenariusz: musisz sklasyfikować 10 000 polskich komentarzy z social media (sentiment + topic), system prompt 8k tokens, output 50 tokens średnio.

Porównanie kosztów dla 10 000 requestów (Sonnet 4.6)

Wariant	Koszt	Czas
Sync API, no cache	~$300 (~1200 zł)	2-3 dni (rate limits)
Sync API + prompt caching	~$40 (~160 zł)	2-3 dni (rate limits)
Batch API, no cache	~$150 (~600 zł)	2-4h typowo
Batch API + prompt caching	~$30 (~120 zł)	2-4h typowo

Oszczędność batch + cache vs naive sync: 90% off. Ten sam workload zamiast $300 → $30. Roczna skala dla zespołu robiącego klasyfikacje codziennie: tysiące dolarów rocznie zaoszczędzone.

Antywzorce

1. Batch dla 5-10 requestów, overhead setup (submit + poll + retrieve) nie zwraca się dla małych workloadów. Sync szybsze i prostsze.
2. Brak idempotencji custom_id, jeśli retry batchu, użycie tych samych custom_id pozwala matchować wyniki. Bez idempotencji gubisz tracking.
3. Polling co sekundę, marnuje API calls. Batch typowo 1-4h, sprawdzaj status co 60s lub używaj webhook.
4. Brak retry logic dla failed, część requestów zawsze faili (rate limit, malformed). Zaplanuj retry budget 5-10% requestów.
5. Brak zapisu wyników, retention 29 dni Anthropic-side. Po pobraniu zapisz do swojego storage (S3, DB) od razu.
6. Mieszanie tools w jednym batch, jeśli różne requesty potrzebują różne tools, OK. Ale jeśli wszystkie te same tools, użyj prompt caching na tools i oszczędź jeszcze więcej.

FAQ

Najczęstsze pytania o Batch API znajdziesz w sekcji FAQ powyżej.

Powiązane artykuły

Claude Code•9 min

Claude Code cena 2026, ile kosztuje i czy jest darmowy

Claude Code cena w PLN i USD, plany Pro i Max, API pay-as-you-go, darmowe kredyty i alternatywy. Najtańsza legalna ścieżka. Stan maj 2026.

Czytaj

Claude Code•9 min

Claude Max plan po polsku, ceny i limity 2026

Plan Claude Max po polsku: ceny Max 5x i 20x, ile zapytań daje, Claude Pro vs Max, Max vs API. Limity sesji i tygodniowe. Stan maj 2026, dla kogo warto.

Czytaj

Claude Code•15 min

Claude Code Skills po polsku, tutorial Agent Skills 2026

Pierwszy polski tutorial Agent Skills w Claude Code. SKILL.md, frontmatter, progressive disclosure, jak tworzyć skille krok po kroku, vs subagents i MCP.

Czytaj