How to Submit your First Batch

This guide will walk you through submitting your first batch to the Doubleword Batch API. The Doubleword Batch API is fully compatible with the OpenAI batch endpoint, making it seamless to switch between providers.

When you submit a batch file, you're sending multiple requests to be processed in parallel. Each request is formatted as a single line in your batch file, allowing for efficient bulk processing.

Batch processing is ideal for workloads that:

• Contain multiple independent requests that can run simultaneously
• Don't require immediate responses
• Would otherwise exceed rate limits if sent individually

1. Prepare your batch file (.jsonl)

Each batch workload starts with a .jsonl file where each line contains a single, valid API request¹.

Each line in your .jsonl file must include these required fields:

• custom_id: Your unique identifier for tracking the request (string, max 64 characters)
• method: HTTP method, always "POST"
• url: API endpoint, typically "/v1/chat/completions"
• body: The actual API request parameters (model, messages, temperature, etc.). This is the same body as your real-time request.

Text-only requests:

{"custom_id": "colorado", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "google/gemma-3-12b-it", "messages": [{"role": "user", "content": "What is the capital of Colorado"}]}}

Multi-modal requests:

{"custom_id": "image-request", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "google/gemma-3-12b-it", "messages": ["role":"user", "content": [{"type": "text", "text": "What is in this image?" }, { "type": "image_url", "image_url": { "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg" }}]]}}

2. Upload your batch input file

Simply point the OpenAI base URL to Doubleword and include your API key²:

from openai import OpenAI

client = OpenAI(
    api_key="your-api-key-here",
    base_url="https://app.doubleword.ai/ai/v1"
)

batch_input_file = client.files.create(
    file=open("batchinput.jsonl", "rb"),
    purpose="batch"
)

print(batch_input_file)

Files can also be uploaded via the Doubleword Console. To do so:

1. Navigate to the Batches section
2. If you want to dispatch the file for batch processing immediately, click the Create First Batch button. If you want to upload the file for later processing, click the files tab, and click Upload first file.
3. Upload your .jsonl file

3. Create the Batch

Once you have uploaded the file, you can now create the batch.

from openai import OpenAI
client = OpenAI()

batch_input_file_id = batch_input_file.id
client.batches.create(
    input_file_id=batch_input_file_id,
    endpoint="/v1/chat/completions",
    completion_window="24h",
    metadata={
        "description": "daily eval job"
    }
)

Completion window can be either "24h" or "1h". "24h" gives the very best price, but "1hr" means you get the results back quicker.

4. Tracking your batches progress

The Doubleword Console contains tools to track the completion of the requests in your batch in real time. You can view each response as requests complete, as well as the price of your batch, and the number of completed requests.

5. Retrieving results

When a batch is triggered, the Doubleword Batch engine will create two files, an Error file, and an Output file. The error file contains details on any request that failed, while the output file contains all the outputs from valid requests.

These files are accessible as soon as the batch is triggered ³