BatchCollector API

The BatchCollector provides a high-level, fluent API for creating batch files. Its structure mimics the official openai client, making it the ideal tool for adding individual, distinct requests to a single batch file.

The first step is to instantiate the collector with the path to your desired output file.

from openbatch import BatchCollector

# All requests will be appended to this file
collector = BatchCollector(batch_file_path="my_batch_job.jsonl") 

Once initialized, you can use the helper attributes (chat.completions, responses, embeddings) to add requests.

---

Chat Completions API (collector.chat.completions)

This interface is used to add requests to the /v1/chat/completions endpoint.

create(...)

Adds a standard chat completion request to the batch file. Use this for general-purpose text generation, question answering, or any standard chat interaction.

Example

collector.chat.completions.create(
    custom_id="chat-req-1",
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is the capital of the Netherlands?"}
    ],
    temperature=0.7
)

API Reference

Creates a standard ChatCompletionsRequest and adds it to the batch file. Use it like the OpenAI().chat.completions.create() method.

Parameters:

Name	Type	Description	Default
custom_id	str	A unique ID for the request in the batch file.	required
model	str	The model ID to use for the request.	required
**kwargs		Additional parameters for the ChatCompletionsRequest.	{}

Source code in openbatch/collector.py

def create(self, custom_id: str, model: str, **kwargs) -> None:
    """
    Creates a standard ChatCompletionsRequest and adds it to the batch file. Use it like the `OpenAI().chat.completions.create()` method.

    Args:
        custom_id (str): A unique ID for the request in the batch file.
        model (str): The model ID to use for the request.
        **kwargs: Additional parameters for the ChatCompletionsRequest.
    """
    request = ChatCompletionsRequest.model_validate({"model": model, **kwargs})
    self._add_request(custom_id, request)

parse(...)

Adds a chat completion request that enforces a structured JSON output based on a Pydantic model. This is perfect for data extraction, classification, or when you need a predictable, machine-readable response.

Example

from pydantic import BaseModel, Field

# 1. Define your desired output structure
class CityInfo(BaseModel):
    city: str
    country: str
    population: int = Field(description="Estimated population")

# 2. Add the request using .parse()
collector.chat.completions.parse(
    custom_id="chat-json-req-2",
    model="gpt-4o",
    response_format=CityInfo, # Pass the Pydantic model here
    messages=[
        {"role": "user", "content": "Extract information about Paris, France."}
    ]
)

API Reference

Creates a ChatCompletionsRequest, optionally enforcing a JSON output structure, and adds it to the batch file. Use it like the OpenAI().chat.completions.parse() method.

Parameters:

Name	Type	Description	Default
custom_id	str	A unique ID for the request in the batch file.	required
model	str	The model ID to use for the request.	required
response_format	Optional[Type[BaseModel]]	An optional Pydantic model to define the desired JSON output structure.	None
**kwargs		Additional parameters for the ChatCompletionsRequest (e.g., messages, temperature).	{}

Source code in openbatch/collector.py

def parse(self, custom_id: str, model: str, response_format: Optional[type[BaseModel]] = None, **kwargs) -> None:
    """
    Creates a ChatCompletionsRequest, optionally enforcing a JSON output structure,
    and adds it to the batch file. Use it like the `OpenAI().chat.completions.parse()` method.

    Args:
        custom_id (str): A unique ID for the request in the batch file.
        model (str): The model ID to use for the request.
        response_format (Optional[Type[BaseModel]]): An optional Pydantic model
            to define the desired JSON output structure.
        **kwargs: Additional parameters for the ChatCompletionsRequest (e.g., messages, temperature).
    """
    request = ChatCompletionsRequest.model_validate({"model": model, **kwargs})
    if response_format is not None:
        request.set_output_structure(response_format)
    self._add_request(custom_id, request)

---

Responses API (collector.responses)

This interface is used to add requests to the /v1/responses endpoint, which is optimized for specific features like reusable prompts and advanced tool use.

create(...)

Adds a standard responses API request to the batch file.

Example

collector.responses.create(
    custom_id="resp-req-1",
    model="gpt-4o",
    instructions="You are a travel agent.",
    input="Suggest three activities to do in Amsterdam."
)

API Reference

Creates a standard ResponsesRequest and adds it to the batch file. Use it like the OpenAI().responses.create() method.

Parameters:

Name	Type	Description	Default
custom_id	str	A unique ID for the request in the batch file.	required
model	str	The model ID to use for the request.	required
**kwargs		Additional parameters for the ResponsesRequest.	{}

Source code in openbatch/collector.py

def create(self, custom_id: str, model: str, **kwargs) -> None:
    """
    Creates a standard ResponsesRequest and adds it to the batch file. Use it like the `OpenAI().responses.create()` method.

    Args:
        custom_id (str): A unique ID for the request in the batch file.
        model (str): The model ID to use for the request.
        **kwargs: Additional parameters for the ResponsesRequest.
    """
    request = ResponsesRequest.model_validate({"model": model, **kwargs})
    self._add_request(custom_id, request)

parse(...)

Adds a responses API request that enforces a structured JSON output based on a Pydantic model. This works similarly to the chat.completions.parse method.

Example

from pydantic import BaseModel
from typing import List

# 1. Define your desired output structure
class ItineraryItem(BaseModel):
    activity: str
    description: str
    estimated_duration_hours: float

class TravelPlan(BaseModel):
    city: str
    suggestions: List[ItineraryItem]

# 2. Add the request using .parse()
collector.responses.parse(
    custom_id="resp-json-req-2",
    model="gpt-4o",
    text_format=TravelPlan, # Pass the Pydantic model here
    instructions="Create a travel plan based on the user's request.",
    input="I have one day in Tokyo. What should I do?"
)

API Reference

Creates a ResponsesRequest, optionally enforcing a JSON output structure, and adds it to the batch file. Use it like the OpenAI().responses.parse() method.

Parameters:

Name	Type	Description	Default
custom_id	str	A unique ID for the request in the batch file.	required
model	str	The model ID to use for the request.	required
text_format	Optional[Type[BaseModel]]	An optional Pydantic model to define the desired JSON output structure for the response.	None
**kwargs		Additional parameters for the ResponsesRequest (e.g., instructions, input, temperature).	{}

Source code in openbatch/collector.py

def parse(self, custom_id: str, model: str, text_format: Optional[type[BaseModel]] = None, **kwargs) -> None:
    """
    Creates a ResponsesRequest, optionally enforcing a JSON output structure,
    and adds it to the batch file. Use it like the `OpenAI().responses.parse()` method.

    Args:
        custom_id (str): A unique ID for the request in the batch file.
        model (str): The model ID to use for the request.
        text_format (Optional[Type[BaseModel]]): An optional Pydantic model
            to define the desired JSON output structure for the response.
        **kwargs: Additional parameters for the ResponsesRequest (e.g., instructions, input, temperature).
    """
    request = ResponsesRequest.model_validate({"model": model, **kwargs})
    if text_format is not None:
        request.set_output_structure(text_format)
    self._add_request(custom_id, request)

---

Embeddings API (collector.embeddings)

This interface is used to add requests to the /v1/embeddings endpoint.

create(...)

Adds an embedding request to the batch file. You can provide a single string or a list of strings as input.

Example

collector.embeddings.create(
    custom_id="embed-req-1",
    model="text-embedding-3-small",
    inp="OpenAI batching is a powerful feature.",
    dimensions=256
)

API Reference

Creates an EmbeddingsRequest and adds it to the batch file. Use it like the OpenAI().embeddings.create() method.

Parameters:

Name	Type	Description	Default
custom_id	str	A unique ID for the request in the batch file.	required
model	str	The model ID to use for the request.	required
inp	Union[str, list[str]]	The input text(s) to be embedded.	required
**kwargs		Additional parameters for the EmbeddingsRequest.	{}

Source code in openbatch/collector.py

def create(self, custom_id: str, model: str, inp: Union[str, list[str]], **kwargs) -> None:
    """
    Creates an EmbeddingsRequest and adds it to the batch file. Use it like the `OpenAI().embeddings.create()` method.

    Args:
        custom_id (str): A unique ID for the request in the batch file.
        model (str): The model ID to use for the request.
        inp (Union[str, list[str]]): The input text(s) to be embedded.
        **kwargs: Additional parameters for the EmbeddingsRequest.
    """
    request = EmbeddingsRequest.model_validate({"model": model, "input": inp, **kwargs})
    BatchJobManager.add(custom_id, request, self.batch_file_path)