Image requests

Use image responses with a predictable API request.

Check image request handling through the OpenAI-compatible images endpoint with returned URLs or b64_json payloads while keeping prompts safe, credentials server-side, and image usage visible.

View request shape Review authentication

Last updated: July 6, 2026. Examples use safe placeholders and do not include real API keys, secrets, customer payloads, or sensitive prompts.

Default path

Start with one image, a standard square size, and url response format. Add larger sizes or base64 only when the workflow needs them.

Setup path

Four steps from prompt to a returned asset shape.

Step 1

Authenticate server-side

Use an API key with images:write scope from trusted server-side code.

Open section

Step 2

Send a prompt

Post a safe prompt, image count, size, and response format to the images endpoint.

Open section

Step 3

Read returned assets

Use returned URLs or b64_json payloads according to the response_format your app requested.

Open section

Step 4

Watch image usage

Image requests record request volume, prompt tokens, and returned image items for logs and rate-limit review.

Open section

Endpoint

Post prompts to the images endpoint.

Use the /v1 images route with a scoped server-side key before image workflows reach customers. Keep prompt content safe and avoid placing sensitive data in image requests.

Image request endpoint requirements and notes.
Item	Value	Notes
Method	POST	Send JSON to the images endpoint.
Endpoint	https://unlimitedcodex.com/v1/images/generations	Use the OpenAI-compatible /v1 images path.
Authorization	Bearer token	Use a scoped API key with images:write access.
Content type	application/json	The request body must be valid JSON.

Request shape

Keep the first request small.

Start with one image and url output while validating the flow. Increase count, size, or inline base64 only after your UI and rate handling are ready.

Image request fields, status, and notes.
Field	Status	Notes
model	Recommended	Pass an image model value explicitly. Use the model value from your delivered setup details.
prompt	Required	Send a non-empty prompt up to 4000 characters. Avoid secrets, regulated data, and customer-identifying details.
n	Optional	Request 1 to 4 images. The default is 1.
size	Optional	Use 256x256, 512x512, 1024x1024, 1024x1792, or 1792x1024. The default is 1024x1024.
response_format	Optional	Use url for a retrievable asset reference or b64_json for inline base64 data.

const response = await fetch("https://unlimitedcodex.com/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.UCX_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "ucx-image-1",
    prompt: "A clean product illustration of an API usage dashboard.",
    n: 1,
    size: "1024x1024",
    response_format: "url"
  })
});

const body = await response.json();

if (!response.ok) {
  throw new Error(body.error?.code ?? "image_request_failed");
}

const firstImageUrl = body.data[0].url;

Response shape

Read the asset format your app requested.

The response includes request metadata and one data item per returned image. Use url or b64_json based on response_format.

Image response fields, meanings, and notes.
Field	Meaning	Notes
id	image request ID	Use for logs and support escalation.
created	Unix timestamp	Indicates when the response was created.
model	model string	Matches the requested model value.
size	requested size	Matches the size accepted by the endpoint.
data[].url	asset URL	Returned when response_format is url.
data[].b64_json	base64 asset data	Returned when response_format is b64_json.

{
  "id": "img_example",
  "created": 1783372800,
  "model": "ucx-image-1",
  "size": "1024x1024",
  "data": [
    {
      "url": "https://unlimitedcodex.com/v1/images/example.png",
      "revised_prompt": "A clean product illustration of an API usage dashboard."
    }
  ]
}

{
  "model": "ucx-image-1",
  "prompt": "A simple square app icon for an internal tool.",
  "n": 1,
  "size": "512x512",
  "response_format": "b64_json"
}

Limits and errors

Plan for image usage and complete responses.

Image request workflows can create sharper usage spikes than text-only requests. Check package fit and 429 handling before launch campaigns or batch jobs.

Package rate limits Review errors

The current image endpoint does not stream partial progress; the response returns after the request completes.

Each returned image item is logged for usage visibility, and each call counts as one request.

Prompt text also contributes to token and cost estimates.

Use small n values while validating a workflow, then increase only when the product needs multiple variations.

Handle 429 rate responses before background image jobs create a user-visible failure.

FAQ

Image request questions.

Which image endpoint should I call?

Use POST /v1/images/generations with a Bearer API key, JSON request body, model, prompt, optional image count, optional size, and optional response_format.

Which scope does an image key need?

Use an API key with images:write scope. Keep it server-side and never expose it in browser code, mobile bundles, logs, or support messages.

Can image requests stream progress?

No. The current endpoint returns a complete response after the request finishes. Build user-facing loading states and timeout handling in your app.

Should I request url or b64_json?

Use url when your app can fetch or store an asset reference. Use b64_json when your app needs inline image data and can handle larger response bodies.

Free tools

Plan image request volume

Validate payloads, estimate quota impact, compare package costs, and build request snippets before launch.

Browse all tools

Request Validator

Validate chat, embeddings, and image JSON payloads against unlimitedcodex OpenAI-compatible rules.

Quota Estimator

Convert MAU and prompt assumptions into monthly tokens, requests, and quota threshold warnings.

Cost Calculator

Estimate OpenAI monthly spend and compare it to flat unlimitedcodex weekly or monthly packages.

Request Builder

Build chat completion JSON visually and export cURL, JavaScript, or Python snippets.

Next step

Pair image request handling with rate limits and error handling.

Before customers depend on image output, confirm prompt policy, image usage, retry behavior, and response storage.

Package rate limits Review embeddings