A Practical Guide to Generating Images with GPT Image 2 on Ace Data Cloud

Generating images from code is useful only when the interface is predictable: you want a clear endpoint, a small request body, a stable response shape, and enough controls to fit real product workflows.

This guide walks through the GPT Image 2 / 2.5 image generation API on Ace Data Cloud as a builder would use it: one endpoint, a few important fields, and practical patterns for product mockups, editorial graphics, and background jobs.

What you can do

The image generation API lets you send a text prompt to https://api.acedata.cloud/openai/images/generations and receive generated image URLs in data[].url. The documented model options include gpt-image-2, gpt-image-2.5-flare, gpt-image-2.5-sunburst, their corresponding :official variants, and gpt-image-2:reverse.

For most first integrations, start with gpt-image-2. If your workflow cares more about speed, the guide describes gpt-image-2.5-flare as the faster option. If you need higher fidelity and more fine-grained control, gpt-image-2.5-sunburst is the documented option to consider.

• Create a single generated image for an article, product concept, or internal design brief.
• Generate 2-10 variations with n when you want several candidates from the same prompt.
• Use exact dimensions for square thumbnails, 16:9 covers, or 9:16 vertical creatives.
• Switch to an asynchronous callback when synchronous generation can time out.

How it works

The API is a JSON-over-HTTP interface. You authenticate with Authorization: Bearer ..., send Content-Type: application/json, and post a body containing at least a model and a prompt. A successful synchronous request returns created and data; the generated image URL is read from data[].url.

The prompt can be detailed: the documentation states it supports up to 32,000 characters. That is helpful when you need to encode brand constraints, composition, lighting, exclusions, or a short design brief. Keep the prompt readable and structured: subject, layout, style, colors, constraints, and what should not appear.

Send the first request

Here is the minimal shape of a real request. Replace YOUR_API_KEY with your Ace Data Cloud API key and adjust the prompt for your use case.

curl https://api.acedata.cloud/openai/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Minimal editorial product illustration: one plain white ceramic coffee mug centered on a solid cobalt blue tabletop, pale cream background, soft shadow, clean geometric shapes, no text, no logo, portrait composition",
    "size": "1024x1536"
  }'

In your application code, do not assume there is only one output forever. Read data as an array and store each url with the request metadata you care about: prompt version, model, size, and user or job identifier.

{"created":1790000000,"data":[{"url":"https://cdn.example.com/generated-image.png"}]}

Choose sizes deliberately

The size field accepts auto or WIDTHxHEIGHT. When specifying pixels directly, the documented constraints are precise: width and height must be multiples of 16, the longest side must not exceed 3840, total pixels must be between 655,360 and 8,294,400, and the aspect ratio must not exceed 3:1.

Use auto while exploring prompt direction. Use exact dimensions once the image becomes part of a UI, CMS, or publishing pipeline. The documentation lists common dimensions such as 1024x1024 for 1:1, 1536x1024 for 4:3, 1024x1536 for 3:4, 1792x1024 for 16:9, and 1024x1792 for 9:16.

Generate multiple candidates

When you need variations, choose n from 1 to 10. This is useful for creative review flows: one request can produce several candidates, and your UI can let a human pick the best one before publishing or saving it to an image library.

curl https://api.acedata.cloud/openai/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2","prompt":"A small fox reading under a glowing mushroom, watercolor illustration","size":"1536x1024","n":2}'

One important edge case: the documentation notes that when response_format is b64_json, only n: 1 is supported. If you need multiple outputs, use URL responses and process the returned data array.

Use callbacks for long-running jobs

For interactive prototypes, a synchronous request is the easiest place to start. For production workflows, especially when users can queue image jobs, consider callback_url. With callback_url, the API first returns a task_id and posts the final result to your endpoint when the task completes.

{"model":"gpt-image-2","prompt":"A product poster with clear typography","size":"1024x1024","callback_url":"https://example.com/webhooks/images"}

Your receiver should use task_id for deduplication, then validate the request source and data format before saving the generated URLs. This makes retries safer and avoids duplicate images when network delivery is noisy.

Troubleshooting checklist

• 400: check the combination of model, prompt, size, n, and response_format.
• 401: verify the API key and the Authorization: Bearer ... header.
• 429: requests are too frequent; retry later.
• 504: synchronous generation timed out; use callback_url.

Error responses include error.code, error.message, and trace_id. If you need to report a failed request, include the trace_id and never include the API key.

Where to go next

The cleanest first implementation is a small wrapper function: accept a prompt and size, post to the generation endpoint, return an array of image URLs, and log the model plus trace metadata for debugging. Once that works, add n for review workflows and callback_url for background jobs.

For the complete field list and current model details, read the OpenAI Images Generations API Integration Guide.