Batch Processing
Batch processing with the Batch API
The new Batch API allows to create async batch jobs for a lower price and with higher rate limits.
Batches will be completed within 24h, but may be processed sooner depending on global usage.
Ideal use cases for the Batch API include:
- Tagging, captioning, or enriching content on a marketplace or blog
- Categorizing and suggesting answers for support tickets
- Performing sentiment analysis on large datasets of customer feedback
- Generating summaries or translations for collections of documents or articles
and much more!
This cookbook will walk you through how to use the Batch API with a couple of practical examples.
We will start with an example to categorize movies using gpt-4o-mini, and then cover how we can use the vision capabilities of this model to caption images.
Please note that multiple models are available through the Batch API, and that you can use the same parameters in your Batch API calls as with the Chat Completions endpoint.
Setup
First example: Categorizing movies
In this example, we will use gpt-4o-mini to extract movie categories from a description of the movie. We will also extract a 1-sentence summary from this description.
We will use JSON mode to extract categories as an array of strings and the 1-sentence summary in a structured format.
For each movie, we want to get a result that looks like this:
{
categories: ['category1', 'category2', 'category3'],
summary: '1-sentence summary'
}
Loading data
We will use the IMDB top 1000 movies dataset for this example.
Processing step
Here, we will prepare our requests by first trying them out with the Chat Completions endpoint.
Once we're happy with the results, we can move on to creating the batch file.
TITLE: The Shawshank Redemption
OVERVIEW: Two imprisoned men bond over a number of years, finding solace and eventual redemption through acts of common decency.
RESULT: {
"categories": ["drama"],
"summary": "Two imprisoned men develop a deep bond over the years, ultimately finding redemption through their shared acts of kindness."
}
----------------------------
TITLE: The Godfather
OVERVIEW: An organized crime dynasty's aging patriarch transfers control of his clandestine empire to his reluctant son.
RESULT: {
"categories": ["crime", "drama"],
"summary": "An aging crime lord hands over his empire to his hesitant son."
}
----------------------------
TITLE: The Dark Knight
OVERVIEW: When the menace known as the Joker wreaks havoc and chaos on the people of Gotham, Batman must accept one of the greatest psychological and physical tests of his ability to fight injustice.
RESULT: {
"categories": ["action", "thriller", "superhero"],
"summary": "Batman faces a formidable challenge as the Joker unleashes chaos on Gotham City."
}
----------------------------
TITLE: The Godfather: Part II
OVERVIEW: The early life and career of Vito Corleone in 1920s New York City is portrayed, while his son, Michael, expands and tightens his grip on the family crime syndicate.
RESULT: {
"categories": ["crime", "drama"],
"summary": "The film depicts the early life of Vito Corleone and the rise of his son Michael within the family crime syndicate in 1920s New York City."
}
----------------------------
TITLE: 12 Angry Men
OVERVIEW: A jury holdout attempts to prevent a miscarriage of justice by forcing his colleagues to reconsider the evidence.
RESULT: {
"categories": ["drama", "thriller"],
"summary": "A jury holdout fights to ensure justice is served by challenging his fellow jurors to reevaluate the evidence."
}
----------------------------
Creating the batch file
The batch file, in the jsonl format, should contain one line (json object) per request.
Each request is defined as such:
{
"custom_id": <REQUEST_ID>,
"method": "POST",
"url": "/v1/chat/completions",
"body": {
"model": <MODEL>,
"messages": <MESSAGES>,
// other parameters
}
}
Note: the request ID should be unique per batch. This is what you can use to match results to the initial input files, as requests will not be returned in the same order.
Uploading the file
FileObject(id='file-lx16f1KyIxQ2UHVvkG3HLfNR', bytes=1127310, created_at=1721144107, filename='batch_tasks_movies.jsonl', object='file', purpose='batch', status='processed', status_details=None)
Creating the batch job
Checking batch status
Note: this can take up to 24h, but it will usually be completed faster.
You can continue checking until the status is 'completed'.
Retrieving results
Reading results
Reminder: the results are not in the same order as in the input file. Make sure to check the custom_id to match the results against the input requests
TITLE: American Psycho
OVERVIEW: A wealthy New York City investment banking executive, Patrick Bateman, hides his alternate psychopathic ego from his co-workers and friends as he delves deeper into his violent, hedonistic fantasies.
RESULT: {
"categories": ["thriller", "psychological", "drama"],
"summary": "A wealthy investment banker in New York City conceals his psychopathic alter ego while indulging in violent and hedonistic fantasies."
}
----------------------------
TITLE: Lethal Weapon
OVERVIEW: Two newly paired cops who are complete opposites must put aside their differences in order to catch a gang of drug smugglers.
RESULT: {
"categories": ["action", "comedy", "crime"],
"summary": "An action-packed comedy about two mismatched cops teaming up to take down a drug smuggling gang."
}
----------------------------
TITLE: A Star Is Born
OVERVIEW: A musician helps a young singer find fame as age and alcoholism send his own career into a downward spiral.
RESULT: {
"categories": ["drama", "music"],
"summary": "A musician's career spirals downward as he helps a young singer find fame amidst struggles with age and alcoholism."
}
----------------------------
TITLE: From Here to Eternity
OVERVIEW: In Hawaii in 1941, a private is cruelly punished for not boxing on his unit's team, while his captain's wife and second-in-command are falling in love.
RESULT: {
"categories": ["drama", "romance", "war"],
"summary": "A drama set in Hawaii in 1941, where a private faces punishment for not boxing on his unit's team, amidst a forbidden love affair between his captain's wife and second-in-command."
}
----------------------------
TITLE: The Jungle Book
OVERVIEW: Bagheera the Panther and Baloo the Bear have a difficult time trying to convince a boy to leave the jungle for human civilization.
RESULT: {
"categories": ["adventure", "animation", "family"],
"summary": "An adventure-filled animated movie about a panther and a bear trying to persuade a boy to leave the jungle for human civilization."
}
----------------------------
Second example: Captioning images
In this example, we will use gpt-4-turbo to caption images of furniture items.
We will use the vision capabilities of the model to analyze the images and generate the captions.
Loading data
We will use the Amazon furniture dataset for this example.
Processing step
Again, we will first prepare our requests with the Chat Completions endpoint, and create the batch file afterwards.
CAPTION: A stylish white free-standing shoe rack featuring multiple layers and eight double hooks, perfect for organizing shoes and accessories in living rooms, bathrooms, or hallways.
CAPTION: Set of 2 black leather dining chairs featuring a sleek design with vertical stitching and sturdy wooden legs.
CAPTION: The MUYETOL Plant Repotting Mat is a waterproof, portable, and foldable gardening work mat measuring 26.8" x 26.8", designed for easy soil changing and indoor transplanting.
CAPTION: Absorbent non-slip doormat featuring the phrase "It's a good day to play PICKLEBALL" with paddle graphics, measuring 16x24 inches.
CAPTION: Set of 4 foldable TV trays in grey, featuring a compact design with a stand for easy storage, perfect for small spaces.
Creating the batch job
As with the first example, we will create an array of json tasks to generate a jsonl file and use it to create the batch job.
Getting results
As with the first example, we can retrieve results once the batch job is done.
Reminder: the results are not in the same order as in the input file. Make sure to check the custom_id to match the results against the input requests
CAPTION: Brushed brass pedestal towel rack with a sleek, modern design, featuring multiple bars for hanging towels, measuring 25.75 x 14.44 x 32 inches.
CAPTION: Black round end table featuring a tempered glass top and a metal frame, with a lower shelf for additional storage.
CAPTION: Black collapsible and height-adjustable telescoping stool, portable and designed for makeup artists and hairstylists, shown in various stages of folding for easy transport.
CAPTION: Ergonomic pink gaming chair featuring breathable fabric, adjustable height, lumbar support, a footrest, and a swivel recliner function.
CAPTION: A set of two Glitzhome adjustable bar stools featuring a mid-century modern design with swivel seats, PU leather upholstery, and wooden backrests.
Wrapping up
In this cookbook, we have seen two examples of how to use the new Batch API, but keep in mind that the Batch API works the same way as the Chat Completions endpoint, supporting the same parameters and most of the recent models (gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-3.5-turbo...).
By using this API, you can significantly reduce costs, so we recommend switching every workload that can happen async to a batch job with this new API.