OpenAI Images Generations API: request the canvas your interface needs

Choose the wrong canvas for a product banner and the image may look fine until the layout crops the headline or trims the subject. The usual fix is another generation, followed by manual resizing. With the OpenAI Images Generations API on Ace Data Cloud, we can request the canvas our interface needs in the same call that creates the image.

The useful twist is how the standard gpt-image-2 route handles that canvas. We can pass a custom WIDTHxHEIGHT value within the documented limits, while the standard channel remains priced at 0.11 Credits per successful image. A wider canvas does not create a separate size surcharge on that route.

One endpoint covers several image model families

We send a text prompt to POST /openai/images/generations. The endpoint accepts DALL-E models, the GPT Image family, and the Nano Banana family. That lets us keep the request shape stable while choosing a model for a particular job.

For gpt-image-2, model and prompt do most of the work. The size field controls the canvas. The n field requests between 1 and 10 images, although response_format: "b64_json" supports only n: 1. DALL-E 3 also supports only n: 1.

The integration guide on Ace Data Cloud documents common presets such as 1024x1024, 1536x1024, 1024x1536, 1792x1024, and 1024x1792. With gpt-image-2, we can also supply a custom size. Both dimensions must be multiples of 16, the longer side must be no more than 3840 pixels, and the total canvas must contain no more than 8,294,400 pixels. An invalid form returns a 400 response.

A real request for a landscape editorial image

Here is a request using the production path and a documented model. Replace the token placeholder with an API token from the Ace Data Cloud console.

curl -X POST "https://api.acedata.cloud/openai/images/generations" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A soft, poetic children’s book illustration of a small fox reading a book under a glowing mushroom in a moonlit forest. Watercolor and pencil texture, gentle pastel colors, dreamy atmosphere, hand-drawn feel.",
    "size": "1536x1024",
    "n": 1
  }'

The request asks for one landscape image. model selects the standard gpt-image-2 channel. prompt describes the content and treatment. size asks for a 3:2 canvas, and n limits the result to one image.

A documented successful response has this shape:

{
  "success": true,
  "task_id": "ab58a5df-6f46-4874-bff6-93169e2849a3",
  "created": 1777048800,
  "data": [
    {
      "revised_prompt": "A cinematic portrait of a young woman standing in a convenience store at night, illuminated by soft pink and cyan neon signs through the window. Shot on 35mm film, shallow depth of field, slight grain, melancholic mood.",
      "url": "https://platform.cdn.acedata.cloud/gpt-image/ab58a5df-6f46-4874-bff6-93169e2849a3_0.png"
    }
  ]
}

success confirms that the generation completed. task_id identifies the job. created is the Unix timestamp attached to the result. data is an array because one request can return several images. Inside each item, revised_prompt records the prompt used for that result, and url points to the hosted image.

The response example comes from a different documented prompt than the request above, so its revised_prompt describes a cinematic portrait. In production code, we should read the fields rather than compare the response text with a hard-coded prompt.

Custom size changes the canvas, not the standard-channel rate

For the standard gpt-image-2 channel, we bill 0.11 Credits multiplied by n. A request for one successful image costs 0.11 Credits. A request that returns four successful images costs 0.44 Credits. When some requested images fail, the integration guide says only the successful images are returned and billed.

The gpt-image-2:reverse route uses the same 0.11 Credits per-image rate. The gpt-image-2:official route is different. It settles from actual text input and image output token usage. Its displayed quality-by-size amount is an estimate rather than the final deduction. The guide gives about 0.0505 Credits for low quality at 1024x1024, plus a small input-token charge, as a typical example.

There is no blanket zero-Credit rule listed for these image-generation choices. The OpenAI service does include a 1.0 Credit initial free amount, but each successful standard gpt-image-2 image still follows the 0.11 Credit billing rule.

The flat standard-channel rate is useful when one application needs several aspect ratios. We can generate a square catalog image and a wide article header without building separate size-based cost branches. We still need to multiply by n, because billing follows the number of successful images.

The auto value makes a design decision for us

Omitting size uses the model’s default aspect ratio. Passing size: "auto" does more. The platform can infer a canvas from explicit dimensions or ratios in the prompt, familiar formats such as paper and device layouts, medium conventions, and the composition itself. The final dimensions are adjusted to supported multiples of 16 and the pixel budget.

That behavior can preserve ratios outside a short preset list, including 1.91:1, 1.85:1, 2.39:1, and ISO paper proportions. It is useful when the prompt names the destination but our code does not know the exact pixel dimensions. When the layout has strict requirements, an explicit WIDTHxHEIGHT value is safer.

We should also avoid assuming that every small request will return the exact pixel count supplied. The guide warns that outputs under the 1K tier may preserve the ratio without strict pixel alignment. Applications that require an exact file size should inspect the downloaded asset and resize it after generation if necessary.

Slow 4K work belongs in an asynchronous flow

The guide says a 4K generation typically takes 4 to 8 minutes. For those calls, callback_url avoids holding an HTTP connection open while the image is being produced. The immediate result provides a task identifier, and the callback delivers the completed response. This is a better fit for queues and background jobs than a long synchronous request.

If the product needs changes to an existing asset rather than a new image, the related OpenAI Images Edits API accepts source images and editing instructions. For a lighter generation route behind the same request style, the Nano Banana Images API is another related service.

For a first integration, we can start with one gpt-image-2 request at n: 1, store task_id with the application job, and copy data[0].url into the record that needs the artwork. Before moving to higher volume, we should validate the returned dimensions and calculate expected spend as 0.11 × successful images. That keeps the image pipeline tied to the fields and billing rules exposed by Ace Data Cloud.

Sources: OpenAI Images Generations API | OpenAI Images Generations API Integration Guide