opendunes
Helpers · 3 min
Copy page ▾

Image generation

Let any text model draw a picture in the middle of its answer, and pay on the picture model's meter.

  1. What it does.
  2. Name it in tools.
  3. Choose the picture.
  4. Read what it bills on.

This page is one helperHelperA tool run for you when a model reaches for it mid-answer: a web search, a page read, a sandbox. Named opendunes:‹name›.More on Helpers →. The list of helpers, and how the charge adds up, sit in Helpers. To draw a picture without a text model in between, call Picture generation directly.

1. What it does

When the model decides a picture is needed, it writes a prompt. A picture model draws it, and the picture's address goes back to the model, which places it in its answer.

Typeopendunes:image_generation
Routes/v1/chat/completions, /v1/responses and /v1/messages
A stepone picture
Stepsat most 30 a request
Bills onthe picture model's meter, in DADAThe Algerian dinar, the one currency the docs show.More on Balance and charges →, beside the text model's tokens

2. Name it in tools

Souk Bot draws a logo for a couscous restaurant in Oran. The sample asks for a square picture in the helper's parameters, allows two pictures, and prints the answer and the charge.

import json
import os
import urllib.request

API_KEY = os.environ["OPENDUNES_API_KEY"]
ADDRESS = "https://opendunes.com/v1/chat/completions"
MODEL = "anthropic/claude-sonnet-4.5"
PROMPT = "Draw a logo for a couscous restaurant in Oran."

body = {
    "model": MODEL,
    "messages": [{"role": "user", "content": PROMPT}],
    "tools": [
        {
            "type": "opendunes:image_generation",
            "parameters": {"aspect_ratio": "1:1"},
        }
    ],
    "max_tool_calls": 2,
}
request = urllib.request.Request(
    ADDRESS,
    data=json.dumps(body).encode(),
    headers={
        "Authorization": "Bearer " + API_KEY,
        "Content-Type": "application/json",
    },
)
with urllib.request.urlopen(request) as response:
    answer = json.load(response)

print(answer["choices"][0]["message"]["content"])
print(answer["usage"]["cost"])

The answer is a 200. Name the helper by its type, opendunes:image_generation; any other spelling of the type is a 400.

3. Choose the picture

Put these in the helper's parameters. Every one but model goes to the picture model as you send it, and which ones it honours depends on the model.

ParameterDoes
modelthe picture model: any one on GET /v1/images/models
size · aspect_ratiothe picture's dimensions, such as 1024x1024, or its shape, such as 16:9
qualitysuch as low, medium or high
backgroundsuch as transparent
output_format · output_compressionpng, jpeg or webp, and a compression from 0 to 100
moderationsuch as auto or low

A request that leaves model out gets the helper's default picture model. To name another, add "model": "<lab>/<model>" to parameters.

4. Read what it bills on

One charge, in DA, from your balanceBalanceWhat you can spend, in DA.More on Balance and charges →, the moment the answer ends: the text model's tokens and each picture, on the picture model's own meter. The picture model's page in Models gives that meter. usage.cost carries the whole of it.

The helper runs another model, so it has a spend cap. Before the model starts, OpenDunes holds money from your wallet for the words and the answer, and writes the cap into the request.

Your requestThe hold
names no stop_server_tools_whenwrites two conditions: the step count, 30 or your max_tool_calls, and a max_cost equal to half of what the wallet has left after the answer's hold; the helper stops at whichever comes first
names stop_server_tools_when with a max_costholds that cap whole; when the wallet cannot pay it, the answer is a 402 that says what the request needs
names stop_server_tools_when without a max_costkeeps your conditions and adds the cap

A cap is a condition on the request:

JSON
{
  "stop_server_tools_when": [
    { "type": "step_count_is", "step_count": 2 },
    { "type": "max_cost", "max_cost_in_dollars": 0.2 }
  ]
}

When the steps or the cap run out, the model answers with what it has gathered.

Don't

Don't give the helper to a model that has no use for a picture. It decides how often to draw, and every picture is charged.

Do

Set max_tool_calls to the number of pictures you want, and pick a picture model whose meter you have read.