API Batch

Avec l’API Batch d’OpenAI, vous pouvez envoyer des lots de requêtes asynchrones à un coût réduit de 50 %, avec des limites de débit distinctes et nettement plus élevées, et un délai de traitement maximal de 24 heures. Ce service est idéal pour les tâches qui ne nécessitent pas de réponse immédiate. Vous pouvez aussi consulter directement la référence de l’API.

Vue d’ensemble

Certains usages de la plateforme OpenAI nécessitent l’envoi de requêtes synchrones. Dans bien des cas, toutefois, vous n’avez pas besoin d’une réponse immédiate, ou les limites de débit vous empêchent d’exécuter rapidement un grand nombre de requêtes. Le traitement par lots se prête notamment aux tâches suivantes :

1. Exécution d’évaluations
2. Classification de grands jeux de données
3. Vectorisation du contenu de dépôts

L’API Batch propose des points de terminaison simples à utiliser. Regroupez vos requêtes dans un seul fichier, lancez leur traitement par lots, consultez l’état du lot pendant l’exécution des requêtes, puis récupérez l’ensemble des résultats une fois le traitement terminé.

Par rapport aux appels directs aux points de terminaison standard, l’API Batch offre les avantages suivants :

1. Coût réduit : une réduction de 50 % par rapport aux API synchrones.
2. Limites de débit plus élevées : une capacité nettement supérieure à celle des API synchrones.
3. Traitement rapide : chaque lot est traité en 24 heures au plus, souvent moins.

Premiers pas

1. Préparez votre fichier de lot

Pour préparer un lot, créez un fichier .jsonl dont chaque ligne contient les détails d’une requête à l’API. Les points de terminaison actuellement disponibles sont les suivants :

• /v1/responses (API Responses)
• /v1/chat/completions (API Chat Completions)
• /v1/embeddings (API Embeddings)
• /v1/completions (API Completions)
• /v1/moderations (guide de modération)
• /v1/images/generations (API Images)
• /v1/images/edits (API Images)

À chaque ligne du fichier d’entrée, le champ body contient les mêmes paramètres que ceux du point de terminaison appelé. Chaque requête doit inclure une valeur custom_id unique qui vous permettra de retrouver son résultat après le traitement. Voici un exemple de fichier d’entrée contenant deux requêtes. Toutes les requêtes d’un même fichier doivent cibler le même modèle.

Pour les appels à /v1/moderations, incluez un champ input dans le corps de chaque requête. Avec omni-moderation-latest, l’API Batch accepte du texte brut ainsi que des tableaux de contenu comprenant du texte ou des images. Comme le point de terminaison de modération synchrone, le service de traitement par lots rejette les requêtes qui spécifient stream=true.

{"custom_id": "request-1", "method": "POST", "url": "/v1/responses", "body": {"model": "gpt-6-luna", "input": "Reply with the word blue.", "reasoning": {"effort": "none"}, "max_output_tokens": 64}}
{"custom_id": "request-2", "method": "POST", "url": "/v1/responses", "body": {"model": "gpt-6-luna", "input": "Reply with the word green.", "reasoning": {"effort": "none"}, "max_output_tokens": 64}}

Exemples d’entrées pour la modération

Requête contenant uniquement du texte :

123456789{
  "custom_id": "moderation-text-1",
  "method": "POST",
  "url": "/v1/moderations",
  "body": {
    "model": "omni-moderation-latest",
    "input": "This is a harmless test sentence."
  }
}

Requête contenant du texte et une image :

1234567891011121314151617181920{
  "custom_id": "moderation-mm-1",
  "method": "POST",
  "url": "/v1/moderations",
  "body": {
    "model": "omni-moderation-latest",
    "input": [
      {
        "type": "text",
        "text": "Describe this image"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://api.nga.gov/iiif/a2e6da57-3cd1-4235-b20e-95dcaefed6c8/full/!800,800/0/default.jpg"
        }
      }
    ]
  }
}

2. Importez votre fichier d’entrée

Comme pour notre API de fine-tuning, vous devez d’abord importer votre fichier d’entrée pour pouvoir le référencer au lancement du traitement. Importez votre fichier .jsonl avec l’API Files.

1
2
3
4
5
6
7
8
9
10import fs from "fs";
import OpenAI from "openai";
const openai = new OpenAI();

const file = await openai.files.create({
  file: fs.createReadStream("fixtures/batchinput.jsonl"),
  purpose: "batch",
});

console.log(file);

1
2
3
4
5
6
7
8
9from openai import OpenAI

client = OpenAI()

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

print(batch_input_file)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27package main

import (
	"context"
	"fmt"
	"os"

	"github.com/openai/openai-go/v3"
)

func main() {
	client := openai.NewClient()
	file, err := os.Open("batchinput.jsonl")
	if err != nil {
		panic(err)
	}
	defer file.Close()

	uploaded, err := client.Files.New(context.Background(), openai.FileNewParams{
		File:    file,
		Purpose: openai.FilePurposeBatch,
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(uploaded.ID)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.files.FileCreateParams;
import com.openai.models.files.FilePurpose;
import java.nio.file.Path;

var file =
    client
        .files()
        .create(
            FileCreateParams.builder()
                .file(Path.of(System.getenv("OPENAI_EXAMPLE_FILE_PATH")))
                .purpose(FilePurpose.BATCH)
                .build());

System.out.println(file.id());

1
2
3
4
5
6
7require "openai"
require "pathname"

client = OpenAI::Client.new
file = Pathname("batchinput.jsonl")
uploaded = client.files.create(file: file, purpose: :batch)
puts(uploaded.id)

1
2
3
4curl https://api.openai.com/v1/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F purpose="batch" \
  -F file="@batchinput.jsonl"

1
2
3openai files create \
  --file batchinput.jsonl \
  --purpose batch

3. Créez le lot

Une fois le fichier d’entrée importé, utilisez l’identifiant de l’objet File correspondant pour créer un lot. Dans cet exemple, supposons que cet identifiant soit file-abc123. Pour le moment, le délai de traitement ne peut prendre que la valeur 24h. Vous pouvez aussi fournir des métadonnées personnalisées avec le paramètre facultatif metadata.

1
2
3
4
5
6
7
8
9
10import OpenAI from "openai";
const openai = new OpenAI();

const batch = await openai.batches.create({
  input_file_id: "file-abc123",
  endpoint: "/v1/responses",
  completion_window: "24h",
});

console.log(batch);

1
2
3
4
5
6
7batch = client.batches.create(
    input_file_id=batch_input_file.id,
    endpoint="/v1/responses",
    completion_window="24h",
    metadata={"description": "nightly eval job"},
)
print(batch)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
)

func main() {
	client := openai.NewClient()
	batch, err := client.Batches.New(context.Background(), openai.BatchNewParams{
		InputFileID:      "file-abc123",
		Endpoint:         openai.BatchNewParamsEndpointV1Responses,
		CompletionWindow: openai.BatchNewParamsCompletionWindow24h,
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(batch.ID)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.batches.BatchCreateParams;

String fileId = "file-abc123";

var batch =
    client
        .batches()
        .create(
            BatchCreateParams.builder()
                .inputFileId(fileId)
                .endpoint(BatchCreateParams.Endpoint.V1_RESPONSES)
                .completionWindow(BatchCreateParams.CompletionWindow._24H)
                .build());

System.out.println(batch.id());

1
2
3
4
5require "openai"

client = OpenAI::Client.new
batch = client.batches.create(input_file_id: "file-abc123", endpoint: "/v1/responses", completion_window: "24h")
puts(batch.id)

1
2
3
4
5
6
7
8curl https://api.openai.com/v1/batches \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_file_id": "file-abc123",
    "endpoint": "/v1/responses",
    "completion_window": "24h"
  }'

1
2
3
4openai batches create \
  --input-file-id file-abc123 \
  --endpoint /v1/responses \
  --completion-window 24h

Cette requête renvoie un objet Batch contenant les métadonnées de votre lot :

1234567891011121314151617181920212223{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/responses",
  "errors": null,
  "input_file_id": "file-abc123",
  "completion_window": "24h",
  "status": "validating",
  "output_file_id": null,
  "error_file_id": null,
  "created_at": 1714508499,
  "in_progress_at": null,
  "expires_at": 1714536634,
  "completed_at": null,
  "failed_at": null,
  "expired_at": null,
  "request_counts": {
    "total": 0,
    "completed": 0,
    "failed": 0
  },
  "metadata": null
}

4. Vérifiez l’état d’un lot

Vous pouvez vérifier l’état d’un lot à tout moment. Cette requête renvoie également un objet Batch.

1
2
3
4
5import OpenAI from "openai";
const openai = new OpenAI();

const batch = await openai.batches.retrieve("batch_abc123");
console.log(batch);

1
2batch = client.batches.retrieve(batch.id)
print(batch)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
)

func main() {
	client := openai.NewClient()
	batch, err := client.Batches.Get(context.Background(), "batch_abc123")
	if err != nil {
		panic(err)
	}
	fmt.Println(batch.Status)
}

1
2
3
4
5
6
7
8import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;

String batchId = "batch_abc123";

var batch = client.batches().retrieve(batchId);

System.out.println(batch.status());

1
2
3
4
5require "openai"

client = OpenAI::Client.new
batch = client.batches.retrieve("batch_abc123")
puts(batch.status)

1
2
3curl https://api.openai.com/v1/batches/batch_abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json"

1
2openai batches retrieve \
  --batch-id batch_abc123

L’état d’un objet Batch peut prendre l’une des valeurs suivantes :

5. Récupérez les résultats

Une fois le traitement terminé, téléchargez les résultats en appelant l’API Files avec la valeur du champ output_file_id de l’objet Batch. Enregistrez-les dans un fichier sur votre machine, ici batch_output.jsonl.

1
2
3
4
5
6
7import OpenAI from "openai";
const openai = new OpenAI();

const fileResponse = await openai.files.content("file-xyz123");
const fileContents = await fileResponse.text();

console.log(fileContents);

1
2
3
4
5
6
7
8
9# Replace the illustrative IDs and URLs below with your own resource values.

from openai import OpenAI

output_file_id = "file_123"
client = OpenAI()

file_response = client.files.content(output_file_id)
print(file_response.text)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23package main

import (
	"context"
	"fmt"
	"io"

	"github.com/openai/openai-go/v3"
)

func main() {
	client := openai.NewClient()
	response, err := client.Files.Content(context.Background(), "file-xyz123")
	if err != nil {
		panic(err)
	}
	defer response.Body.Close()
	contents, err := io.ReadAll(response.Body)
	if err != nil {
		panic(err)
	}
	fmt.Println(string(contents))
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.http.HttpResponse;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.StandardCopyOption;

String fileId = "file-xyz123";

try (HttpResponse content = client.files().content(fileId)) {
  Files.copy(
      content.body(), Path.of("batch_output.jsonl"), StandardCopyOption.REPLACE_EXISTING);
}

1
2
3
4
5require "openai"

client = OpenAI::Client.new
content = client.files.content("file-xyz123")
puts(content.read)

1
2curl https://api.openai.com/v1/files/file-xyz123/content \
  -H "Authorization: Bearer $OPENAI_API_KEY" > batch_output.jsonl

1
2
3openai files content \
  --file-id file-xyz123 \
  --output batch_output.jsonl

Le fichier de sortie .jsonl contient une ligne de réponse pour chaque requête du fichier d’entrée qui a abouti. Pour les requêtes qui ont échoué, les détails des erreurs sont consignés dans un fichier d’erreurs accessible via le champ error_file_id du lot.

L’extrait de sortie suivant montre comment les identifiants relient chaque requête au texte généré. Pour chaque message, lisez le contenu de type output_text dans response.body.output.

{"id": "batch_req_2", "custom_id": "request-2", "response": {"status_code": 200, "request_id": "req_2", "body": {"id": "resp_2", "object": "response", "status": "completed", "output": [{"type": "message", "role": "assistant", "content": [{"type": "output_text", "text": "green"}]}]}}, "error": null}
{"id": "batch_req_1", "custom_id": "request-1", "response": {"status_code": 200, "request_id": "req_1", "body": {"id": "resp_1", "object": "response", "status": "completed", "output": [{"type": "message", "role": "assistant", "content": [{"type": "output_text", "text": "blue"}]}]}}, "error": null}

Le fichier de sortie est automatiquement supprimé 30 jours après la fin du traitement du lot.

6. Annulez un lot

Si nécessaire, vous pouvez annuler un lot en cours de traitement. Son état passe à cancelling jusqu’à la fin des requêtes en cours d’exécution, ce qui peut prendre jusqu’à 10 minutes. Il passe ensuite à cancelled.

1
2
3
4
5import OpenAI from "openai";
const openai = new OpenAI();

const batch = await openai.batches.cancel("batch_abc123");
console.log(batch);

1
2
3
4
5
6
7
8# Replace the illustrative IDs and URLs below with your own resource values.

from openai import OpenAI

batch_id = "batch_123"
client = OpenAI()

client.batches.cancel(batch_id)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
)

func main() {
	client := openai.NewClient()
	batch, err := client.Batches.Cancel(context.Background(), "batch_abc123")
	if err != nil {
		panic(err)
	}
	fmt.Println(batch.Status)
}

1
2
3
4
5
6import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;

String batchId = "batch_abc123";

System.out.println(client.batches().cancel(batchId).status());

1
2
3
4
5require "openai"

client = OpenAI::Client.new
batch = client.batches.cancel("batch_abc123")
puts(batch.status)

1
2
3
4curl https://api.openai.com/v1/batches/batch_abc123/cancel \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST

1
2openai batches cancel \
  --batch-id batch_abc123

7. Obtenez la liste de tous les lots

Vous pouvez consulter la liste de tous vos lots à tout moment. Si vous avez de nombreux lots, utilisez les paramètres limit et after pour récupérer les résultats page par page.

1
2
3
4
5
6
7
8import OpenAI from "openai";
const openai = new OpenAI();

const list = await openai.batches.list();

for await (const batch of list) {
  console.log(batch);
}

1
2
3
4
5from openai import OpenAI

client = OpenAI()

client.batches.list(limit=10)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
)

func main() {
	client := openai.NewClient()
	list := client.Batches.ListAutoPaging(context.Background(), openai.BatchListParams{Limit: openai.Int(10)})
	for list.Next() {
		fmt.Println(list.Current().ID)
	}
	if err := list.Err(); err != nil {
		panic(err)
	}
}

1
2
3
4
5
6
7
8
9import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.batches.BatchListParams;

client
    .batches()
    .list(BatchListParams.builder().limit(10).build())
    .autoPager()
    .forEach(batch -> System.out.println(batch.id()));

1
2
3
4
5
6require "openai"

client = OpenAI::Client.new
client.batches.list(limit: 10).auto_paging_each do |batch|
  puts(batch.id)
end

1
2
3curl https://api.openai.com/v1/batches?limit=10 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json"

1
2openai batches list \
  --limit 10

Modèles disponibles

La plupart des modèles prennent en charge l’API Batch. Vérifiez si c’est le cas du vôtre dans la référence des modèles. GPT-6 Sol et Luna prennent en charge la résidence des données dans l’UE pour les modes de traitement Standard, Flex et Batch. Consultez les critères d’éligibilité à la résidence des données.

GPT Image 2.5 prend en charge la génération d’images et leur modification par lots avec gpt-image-2.5-flare et gpt-image-2.5-sunburst, y compris leurs versions du 2026-09-08. Utilisez /v1/images/generations ou /v1/images/edits et consultez les tarifs de génération d’images pour connaître les prix du traitement par lots.

Limites de débit

Les limites de débit de l’API Batch sont distinctes des limites de débit existantes pour chaque modèle. L’API Batch applique trois types de limites de débit :

1. Limites par lot : un lot peut contenir jusqu’à 50 000 requêtes et son fichier d’entrée peut atteindre 200 Mo. Pour les lots ciblant /v1/embeddings, le nombre d’entrées à vectoriser est également limité à 50 000, toutes requêtes du lot confondues.
2. Tokens de prompt en file d’attente par modèle : chaque modèle impose un nombre maximal de tokens de prompt pouvant être mis en file d’attente pour le traitement par lots. Consultez ces limites dans les paramètres de la plateforme.
3. Limite de débit pour la création de lots : vous pouvez créer jusqu’à 2 000 lots par heure. Si vous devez envoyer davantage de requêtes, augmentez le nombre de requêtes par lot.

L’API Batch n’impose actuellement aucune limite au nombre de tokens de sortie. Comme elle dispose de ses propres limites de débit, les tokens utilisés avec l’API Batch ne sont pas décomptés de vos limites de débit standard par modèle. Vous pouvez ainsi envoyer davantage de requêtes à l’API et traiter plus de tokens.

Expiration des lots

Si le traitement d’un lot ne se termine pas dans le délai prévu, le lot passe à l’état expired. Les requêtes inachevées sont annulées et les réponses aux requêtes terminées sont disponibles dans le fichier de sortie du lot. Les tokens consommés par les requêtes terminées vous sont facturés.

Les requêtes expirées sont consignées dans votre fichier d’erreurs avec le message ci-dessous. Utilisez le champ custom_id pour retrouver les données de chaque requête expirée.

{"id": "batch_req_123", "custom_id": "request-3", "response": null, "error": {"code": "batch_expired", "message": "This request could not be executed before the completion window expired."}}
{"id": "batch_req_123", "custom_id": "request-7", "response": null, "error": {"code": "batch_expired", "message": "This request could not be executed before the completion window expired."}}