Generate and edit images

Three different tasks

• Generation creates an image from words. Use Cherry Paintings or the documented Chatbox Image Creator setup.
• Editing changes an uploaded image. Cherry's single-image .jpeg workflow succeeded; Chatbox 1.23.5 did not send the reference image.
• Understanding describes an image in text. It requires a vision-capable text model and is not proof of generation or editing.

Start with one inexpensive example

1. Ask for a green book and yellow sun on a cream background, without text. Choose <ALBATROSS_IMAGE_MODEL>, one image, low quality and a square request where those controls exist.
2. Wait without repeatedly pressing Send. Once the preview appears, inspect it before requesting revisions. In Chatbox click the image → Download. In Cherry, right-click the completed image → Save As, choose a folder and filename, and wait for Saved.

• Cherry generation and edit steps
• Chatbox generation steps

Supported request settings

• Use the exact image alias returned by GET /v1/models for your key (shown here as <ALBATROSS_IMAGE_MODEL>). The current image route requires the upstream capability gpt-image-2; that upstream name is not necessarily the customer alias. One image per request; no streaming.
• Sizes: 1024x1024, 1536x1024 or 1024x1536; quality: low, medium or high. Omitted settings default to 1024x1024 and low. The tested clients sent model, prompt and n=1, so the defaults applied.
• size=auto is normalized to 1024x1024 before route selection and pricing, regardless of the prompt or input aspect ratio. ImageGen CLI sends medium by default; generation and editing each need a published 1024x1024/medium price. The API's omitted-quality default remains low; an unpriced specification fails before dispatch without silently downgrading quality.
• output_format currently supports only png and defaults to png. SVG, GIF, jpg, jpeg and webp are not valid output formats for the current Sub2API image Provider. The Gateway rejects jpeg and webp before calling Sub2API because this Provider returned PNG for those requests; there is no upstream charge, transcoding or retry. Other image Providers may support additional output formats when their published route capability allows them. Editing still accepts one PNG, JPEG or static WebP input. Responses contain data[].b64_json; save decoded PNG bytes with a .png extension.
• Returned pixel dimensions may differ from the requested size. Inspect the downloaded file; the request setting is not a guaranteed pixel measurement.
• The total image request body is limited to 12 MiB. Editing accepts one PNG, JPEG or static WebP file with the matching MIME type, up to 10 MiB. Masks, batches, multiple inputs, URL input/output, quality=auto, background, output_compression, moderation and input_fidelity are unsupported, even if a client offers them.

How image charges work

Albatross uses the price snapshot captured when the request starts. Where a published dual-price snapshot exists, complete valid image-token evidence uses token pricing; successfully delivered images with incomplete or invalid evidence use its per-image fallback. Old token-only snapshots do not gain a fabricated fallback. The console price and usage record determine your actual charge.

The Gateway image deadline defaults to 120 seconds (administrators can configure up to 300 seconds); use a longer client deadline when configurable. A client timeout or cancellation is not evidence that no image was generated. Before retrying, check Usage or ask support to locate the request. Local acceptance prices are not a promise of future prices.

The Gateway and native image transport do not retry. An SDK or CLI can still retry automatically: disable client retries where supported and avoid repeated submissions. Do not automatically retry image requests after a timeout, image_result_unknown or invalid_image_result. Preserve the request ID and locate the request first; resubmission cannot recover the original result and can cause another generation and charge.

Codex: reuse the existing ImageGen Skill / CLI

Use an installed ImageGen Skill that supports API/CLI mode, with its existing Python/OpenAI SDK dependencies. One Albatross Key must have permission for both the text and image aliases, with generation and edit prices published for the requested image specification. This uses the independent Images API and does not reroute Codex's built-in image tool or enable a Responses image_generation tool. If the installed Skill only supports the built-in tool, this configuration alone cannot make it call Albatross; first use a version with API/CLI support.

Back up and merge the following example into the user-level ~/.codex/config.toml; do not overwrite unrelated settings or duplicate the provider table. If CODEX_HOME is customized, use config.toml in that directory. The root model is the text model that plans and executes tasks: gpt-6-astra is an example, to be replaced by your permitted published text alias. Keep the image model gpt-image-2 in the image task/CLI --model option, not in the root model field. This is one text provider plus an image API call, not two Codex main models.

Replace placeholders before running the export block in the same terminal that launches Codex CLI; the variables last only for that terminal and its children. OPENAI_BASE_URL must equal the provider base_url, including /v1. Restart Codex after changes. For Desktop, make both variables available to the app and tool subprocesses through a launch method supported by your installed version, then fully restart it; exporting them in an unrelated terminal is insufficient. In the Desktop environment-handoff instructions, choose the ImageGen shared-key scheme with OPENAI_API_KEY and OPENAI_BASE_URL, rather than the text-only scheme; do not assume ~/.codex/.env support.

In your practice project, explicitly ask Codex to use the ImageGen Skill's API/CLI mode, with the configured key and base URL, to generate one image or edit one supplied local image and save the result to your chosen output path. Keep n=1 and choose a supported format. The CLI defaults to gpt-image-2; if the published alias differs, require --model <ALBATROSS_IMAGE_MODEL>. No additional script or Skill is needed. Local mock validation covers compatibility; the target Desktop and real provider still require separate acceptance.

model = "gpt-6-astra"
model_provider = "albatross"

[model_providers.albatross]
name = "Albatross"
base_url = "https://staging-gateway.bulakua.com/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"
requires_openai_auth = false

export OPENAI_API_KEY="<ALBATROSS_API_KEY>"
export OPENAI_BASE_URL="https://staging-gateway.bulakua.com/v1"

codex

• Codex CLI configuration
• Desktop configuration and environment

Ask Codex to generate or edit an image

After saving the configuration and restarting Codex with the environment above, paste one of the following prompts into the Codex conversation, not the terminal or config file. Replace the image alias if yours differs. Paths are relative to your practice project; for editing, prepare input/photo.png first or replace it with the actual local path. The output extension must match the requested format.

Codex must be able to read the input, write the output and access the configured Gateway from its tool execution environment. Confirm it selected the Skill's API/CLI mode and your image alias; never print the key. If that mode or its dependencies are unavailable, report the missing prerequisite instead of falling back to another image service. Successful text replies do not prove image access. After one successful image task, check the saved image and the corresponding Albatross Usage entry; text planning and image generation can each incur a charge.

Use the ImageGen Skill in API/CLI mode with the configured Albatross key and base URL. Use gpt-image-2 to generate one watercolor landscape of snowy mountains: n=1, size=auto, quality=medium, output_format=png. Save it as output/image.png. Do not automatically retry after a timeout or uncertain result; report the request ID if available and stop.

Use the ImageGen Skill in API/CLI mode with the configured Albatross key and base URL. Use gpt-image-2 to edit the single local image input/photo.png: replace the background with snowy mountains and preserve the person. Use n=1, size=auto, quality=medium, output_format=png, without a mask or extra parameters. Save it as output/edited.png. Do not automatically retry after a timeout or uncertain result; report the request ID if available and stop.

Costs and getting help

Albatross Usage and wallet records are the customer bill. Client token counters or price estimates are not your bill; upstream procurement costs are separate. Titles, connection tests and tool continuations may each send paid requests. Stop repeated retries when a request fails.

Invalid Key means checking the Albatross credential. Insufficient quota means checking Albatross balance and limits, not buying a client subscription. For Too Many Requests, wait before retrying; for Gateway Timeout, check Usage before sending again. Both clients displayed these errors in controlled tests; only the invalid-key test reached the local Gateway, with a synthetic key. Quota, rate-limit and timeout responses were simulated without upstream calls.

Contact your Albatross service administrator with the client version, model, time and time zone, error text and request ID if visible. Remove keys, account details and private content from screenshots. Check Usage for keys you can view; ask your organization administrator to check an organization-owned key. Missing records do not mean no charge. Cancelling locally does not guarantee zero upstream work or zero charge.

• Keys, permissions and billing
• Technical error reference