batchwork-ai 0.2.2

Unified async batch API for AI providers

Batchwork

Unified async batch API for OpenAI, Anthropic, Google Gemini, Groq, Mistral, Together AI, and xAI. Providers price eligible batch requests up to 50% below standard synchronous calls, and Batchwork gives you that pricing through one typed Python interface and one CLI. It handles provider-specific serialization, submission, polling, and result parsing so you do not have to. Pricing and eligibility remain provider- and model-specific.

• One typed API for provider-native batch jobs
• Text, embedding, and image workloads
• Normalized jobs, results, usage, and errors
• Messages, tools, structured content, and remote media
• Polling, persistent stores, and signed webhooks
• A batchwork CLI and Agent Skill for terminals, scripts, and coding agents
• No provider SDK or JavaScript runtime dependencies

📖 Full documentation: batchwork.ajanraj.com

Installation

Batchwork requires Python 3.11 or newer.

With uv:

uv add batchwork-ai

With pip:

pip install batchwork-ai

Then configure a provider credential:

export OPENAI_API_KEY="..."

See Configuration for every provider credential, endpoint override, model format, and batch limit.

Command-line tool

The same package ships a batchwork command, so you can submit and manage batches without writing Python. Install it with uv tool:

uv tool install batchwork-ai
batchwork --version

Human quick start:

batchwork submit text prompts.txt --model openai/gpt-5
batchwork list
batchwork status BW_RECORD_ID
batchwork results BW_RECORD_ID

Agent and automation quick start:

batchwork --jsonl --quiet run text requests.jsonl --model openai/gpt-5

Machine output uses schema version 1. Global controls such as --jsonl, --profile, and --quiet precede the command. Preserve the first emitted job identity, capture stdout/stderr/exit status separately, and never retry an acceptance-ambiguous submission automatically. Image files are written only when --output-dir is explicit.

If you use a coding agent, the batchwork-ai Agent Skill teaches it the same contract, including when to ask before spending money and how to resume interrupted jobs:

npx skills add ajanraj/batchwork-ai@batchwork-ai

See the CLI guide, configuration and registry reference, machine schema, and exit catalog.

Quickstart

import asyncio

from batchwork import BatchRequest, Batchwork


async def main() -> None:
    async with Batchwork() as client:
        job = await client.batch(
            model="openai/gpt-5.6-sol",
            requests=[BatchRequest(custom_id="hello", prompt="Say hello")],
        )
        await job.wait(timeout=3600)

        for result in await job.collect():
            print(result.custom_id, result.text)


asyncio.run(main())

Submitting returns a BatchJob immediately. Provider processing is asynchronous and may take minutes or, depending on the provider and workload, up to 24 hours.

Models use provider/model form. Results are correlated with requests through custom_id; provider output order is not guaranteed.

Providers

Output workloads supported by Batchwork:

Provider	Text	Embeddings	Image generation
OpenAI	Yes	Yes	Yes
Anthropic	Yes	No	No
Google Gemini	Yes	Yes	Yes
Groq	Yes	No	No
Mistral	Yes	Yes	No
Together AI	Yes	No	No
xAI	Yes	No	Yes

Image, PDF, text-file, and audio inputs for text requests vary separately from output modalities. Provider APIs may also impose model-specific limits. See the provider overview for input support, submission transport, credentials, and restrictions.

Optional Redis store

Install the Upstash Redis integration for persistent polling state:

uv add "batchwork-ai[redis]"
# or
pip install "batchwork-ai[redis]"

The base package does not import or require upstash-redis.

Documentation

• Installation
• Configuration
• Jobs
• Results
• Text, embeddings, and images
• Provider overview
• Polling and webhooks
• Stores
• Security
• Examples
• Public API
• FAQ

License

MIT © Ajanraj

Acknowledgements

Inspired by Hayden Bleasel's Batchwork.