opendunes
Video and batches
Copy page ▾

Batch jobs

POST /v1/batches sends many requests to one model at once; the answers come later, at the model's batch rate, and GET /v1/batches/{id} fetches them.

Request

Send it with an API keyAPI keyThe key you create and send with every request that calls a model.More on API keys →, as JSON. The Batches guide runs one from start to end. Every request in a batch goes to the same route and the same model, and runs on that model's batch entry, picked for you. A batch never streams. The answer is 202 Accepted with the batch's id: ask for it with Batch status until it is done.

FieldNeededYou send
endpointyesthe route every request goes to: /v1/chat/completions, /v1/responses, /v1/messages or /v1/embeddings
modelyesthe model, lab/model, without :batch. A model with no batch entry is refused
requestsyesthe requests, one or more: each {"custom_id": ..., "body": {...}}
custom_idyesin each request: a name of your own, different for every request; its answer comes back under it
bodyyesin each request: the request, in the shape of endpoint. model may be left out; if sent, it is the batch's model. No stream, no audio or video, and a picture or a file only as a public link, http or https
completion_windowno24h, the only window: a batch not done within it ends expired
providerno{"only": [...]}: the providers that may serve it, and no other setting

A shop writes the product copy for its catalogue overnight: three products, three requests, one batch.

import json
import os
import urllib.request

API_KEY = os.environ["OPENDUNES_API_KEY"]
ADDRESS = "https://opendunes.com/v1/batches"
MODEL = "anthropic/claude-sonnet-4.5"
ASK = "Write two lines of shop copy for: "

products = {
    "burnous-01": "Burnous en laine, blanc cassé, taille unique",
    "tapis-07": "Tapis berbère 200 × 300, motifs Ouarsenis",
    "theiere-03": "Théière en cuivre martelé, 1 litre",
}

request = urllib.request.Request(
    ADDRESS,
    data=json.dumps(
        {
            "endpoint": "/v1/chat/completions",
            "model": MODEL,
            "requests": [
                {
                    "custom_id": sku,
                    "body": {
                        "messages": [
                            {"role": "user", "content": ASK + name},
                        ]
                    },
                }
                for sku, name in products.items()
            ],
        }
    ).encode(),
    headers={
        "Authorization": "Bearer " + API_KEY,
        "Content-Type": "application/json",
    },
)
with urllib.request.urlopen(request) as response:
    batch = json.load(response)

print(batch["id"], batch["status"])

Response

202 Accepted, once the batch is taken. Nothing has run yet.

FieldHolds
idthe batch's id: ask for it with GET /v1/batches/{id}
objectbatch
endpointthe route its requests go to
modelthe model, lab/model
completion_window24h
statusvalidating: taken, not yet started
created_atwhen it was taken, in Unix seconds
finalized_atnull until it ends
request_countstotal, completed and failed: how many requests, and how many are done
usagenull until it ends
resultsnull until it ends
errornull, or why the batch failed

What it cost

Nothing when you send it. The batch is charged once, in DADAThe Algerian dinar, the one currency the docs show.More on Balance and charges → from your balanceBalanceWhat you can spend, in DA.More on Balance and charges →, when it ends: the tokens every request used, at the rates of the model's batch entry, which its model page shows. usage.cost on Batch status carries the charge.

  • Picks the price: model, always on its batch entry.
  • Moves the count: every body, each counted as the same request sent on its own would be.
  • Changes the answer, never the bill: custom_id and completion_window.

Your balance must be above zero to send a batch. A batch that ends with nothing counted charges nothing, and a failed batch charges nothing. Asking for a batch, listing and deleting are free.

Errors

error.code carries the status, and error.message says why.

StatusWhen
400a needed field is missing, endpoint is not one of the four, two requests share a custom_id, provider holds more than only, the model has no batch entry, or a request streams, sends audio or video, names another model, or sends a picture or a file that is not a public link; the message names the request by its custom_id
401the key is missing, wrong, disabled or expired
402your balance is at zero or below, cannot pay the request's hold, or the key's cap is spent; error.metadata.limit_source names which, and deposit_url or key_url says where to lift it. After up to 60 seconds of waiting for money your running requests hold, the 402 carries Retry-After: 60
403the key is kept to other models or other addresses, a guardrail's budget is spent, or a guardrail blocked the batch
413the batch is too large to take in one request
422the batch is well formed, but its model or its custom_ids break a batch rule; the message says which
429the provider is limiting its rate; Retry-After says how many seconds to wait
500an unexpected error
502the batch service is down, or a provider failed
503the batch cannot be taken right now; ask again shortly
504the provider did not answer in time

Last modified on