Use the xplaai AI Image Generation API to generate and edit images

The xplaai AI Image Generation API uses POST /v1/images/generations for supported text-to-image, reference-guided and editing workflows. Choose a model, send only its documented fields, and authenticate the request with your xplaai Bearer token. Synchronous and asynchronous response patterns vary by public model, so validate the selected contract before calling it.

Create an API key or check the current image documentation.

Build image generation into products and automations

The image endpoint can support several types of application:

  • text-to-image generation from a written creative brief;
  • reference-guided generation using public URLs or supported base64 input;
  • image editing where the selected model accepts source images;
  • product and marketing visual creation;
  • high-resolution output where the selected contract supports it;
  • a first visual step before an image-to-video workflow.

The practical advantage of one endpoint is simpler application routing. It does not make every model's parameters interchangeable.

Compare the image contracts

Model Useful when you need Verified contract highlights
nano-banana-2 Text-to-image or image-to-image generation Supports 1K, 2K and 4K options; accepts supported public URL or base64 references
nano-banana-pro Higher-quality product and marketing visual workflows Supports 1K, 2K and 4K options with its documented reference-image contract
gpt-image-2 Standard synchronous generation or editing One image per request; JSON reply mode; documented aspect-ratio or pixel-size behavior
gpt-image-2-vip Explicit pixel dimensions within its contract One image per request; maximum side 3840; dimensions in multiples of 16; maximum 3:1 ratio
gpt-image-2-1K An asynchronous GPT Image 2 workflow with multiple references Uses the task workflow and returns the completed content location in task metadata
gpt-image-2-medium A separate GPT Image 2 quality-and-size contract Uses 1K, 2K or 4K imageSize options documented for this public model name

Confirm the live catalog before deployment. A model can be available through the platform while still requiring a distinct request shape.

Make a minimal image request

export XPLA_API_KEY="your_api_key"

curl --request POST \
  --url https://xplaai.com/v1/images/generations \
  --header "Authorization: Bearer $XPLA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "gpt-image-2",
    "prompt": "a clean studio product image on a warm neutral background",
    "images": [],
    "aspectRatio": "1024x1024",
    "replyType": "json"
  }'

This example uses placeholder credentials and the standard gpt-image-2 contract. Do not copy fields from a different model into the request without checking the documentation.

Model-specific fields are not global options

It is tempting to build one oversized request object containing every possible control. That creates ambiguous behavior and difficult-to-debug failures.

Instead, define a request schema per public model:

const requestByModel = {
  "gpt-image-2": {
    allowed: ["prompt", "images", "aspectRatio", "replyType"]
  },
  "nano-banana-2": {
    allowed: ["prompt", "images", "imageSize"]
  },
  "gpt-image-2-medium": {
    allowed: ["prompt", "images", "imageSize"]
  }
};

The exact field list should come from the current xplaai documentation. The principle is stable: validate against the selected model, not against a generic union of every field.

Do not treat imageSize as universal

imageSize applies to documented Banana models and the gpt-image-2-medium contract. Standard gpt-image-2 and gpt-image-2-vip use their own documented size behavior and should reject unsupported fields.

Validate explicit dimensions

For a model that accepts explicit dimensions, validate its limits before sending the request. For gpt-image-2-vip, the current contract includes a maximum side of 3840 pixels, dimensions divisible by 16 and a maximum 3:1 aspect ratio.

Keep reference inputs accessible and controlled

When you pass a public image URL, the generation service must be able to access it. Avoid short-lived signed URLs that expire before processing, and never embed secrets in a URL. When base64 input is supported, enforce file-size and media-type limits in your own application.

Handle the output as authenticated content

A synchronous image response can include an authenticated xplaai content URL. Treat it as a delivery location, not a promise of permanent public hosting.

Your application should:

  1. request the output using authorized access;
  2. copy or process it according to your product's retention policy;
  3. avoid exposing a private content URL in public logs;
  4. store provenance such as model name, prompt version and request options;
  5. follow your own rules for user deletion and media access.

The gpt-image-2-1K workflow is asynchronous and follows the documented task pattern rather than the standard synchronous image response. Do not route it through synchronous-only response handling.

A production checklist for image generation

Validate before you call the API

  • Is the selected model available?
  • Does it support generation, editing or both?
  • Are the number and format of reference images valid?
  • Is the requested size valid for that model?
  • Does the prompt contain data your application should not send externally?

Design for reproducibility

Store the public model name and the exact user-facing options. If your product later changes its defaults, existing generations should still be explainable.

Separate generation from storage

Generation creates the asset. Your application is responsible for deciding where the final asset lives, who can access it and how long it should be retained.

Add human review where the use case requires it

Product claims, logos, likenesses and regulated content may require editorial or legal review. An API response should not automatically become a published ad.

Continue from image to video or a complete commerce workflow

Use the AI video API when you want to animate a generated or supplied reference image. If you need a repeatable commerce pipeline, the Batch Commerce Video Skill can coordinate product inputs and multiple vertical-video outputs.

For developer-controlled composition across media types, return to the unified AI API overview.

Frequently asked questions

Can I generate and edit images through the same endpoint?

The endpoint is shared, but generation and editing support depends on the selected model. Use only the inputs documented for that model.

Can I use a reference image?

Yes, supported models accept reference images through documented public-URL or base64 input. The allowed number and format can differ by model.

Which image model should I use?

Choose by workflow first: generation versus editing, required reference inputs, output size and synchronous versus asynchronous handling. Then compare the current model contracts.

Can the API generate 4K images?

Some documented models support a 4K option. That does not mean every model accepts imageSize: "4K". Confirm the field and limits for your selected model.

Is the returned image URL public forever?

No such assumption should be made. Treat an authenticated content URL as a delivery mechanism and move the asset into storage that matches your application's retention policy.

Can I animate the generated result?

Yes. Pass a supported, accessible image reference to a compatible image-to-video model through the AI video API.

Generate your first image

Create an xplaai API key, choose an image model based on its documented contract, and test a small request before building the full production workflow.