Generate images for a company workflow

POST /v1/images/generations creates a durable Images operation. Use a company API key and a model with a reviewed image.generate contract. A Responses image_generation tool is a separate API contract; it does not use this operation store.

Request

The example performs a potentially paid operation when executed with a real model and key. Replace the model and inspect GET /v1/images/catalog?model=YOUR_MODEL before submitting. Options depend on the selected route.

curl https://api.b2b-llm.com/v1/images/generations \
  -H "Authorization: Bearer $B2B_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: company-label-001' \
  -d '{"model":"YOUR_MODEL","prompt":"A plain product label on a neutral background","n":1,"model_gate":{"async":true}}'

Response and access boundary

An asynchronous acknowledgement is HTTP 202 with object: image.operation, an operation id, status, quote and a result_url. Poll the authenticated operation URL. GET /v1/images/operations/{id}/result returns a completed created/data envelope or the current state. Encoded output is in b64_json; a supported response_format: url returns private relative file URLs, not provider URLs. Supply the company API key when downloading.

Access is bound to the billing owner, originating principal, originating API key and current group context. Another employee's key is not a company-wide file browsing grant. Legacy browser-session keys are not accepted. Since10.49.0 the dedicated Playground Images tab instead uses separate operation-scoped permissions, without revealing a reusable project key.

An identical retry under the same Idempotency-Key returns the existing operation; changing its content produces HTTP 409. Do not rotate the key to recover outcome_unknown or review_required: investigation is required before any new paid request. Only retrieval_failed can use the explicit download-only retry.

There is no advance wallet reserve. accounting_recorded means the canonical usage record was committed, not that settlement has already completed. Missing token usage leaves the price unknown instead of guessing a zero amount. Files expire after 24 hours; idempotency records remain. See operation handling and editing.

Optional model_gate.quote_sha256 binds a previously approved route quote; changed context fails before dispatch. The Images tab uses scoped permissions without exposing permanent API secrets.

Reading the operation valuation

For a company request, distinguish the preliminary Price quote and Usage Limit quote from the Calculated cost and calculated limit valuation recorded after processing. None of these labels alone confirms the company balance has settled. The files_available flag also checks that saved outputs exist and their download period remains open; a pending operation may have no files yet.

Image-based billing can accept a consistent aggregate-only token report without pretending it contains modality-specific usage. The response marks this as usage.token_usage_status=aggregate_only_not_priced and places the supplied totals in usage.reported_tokens. A missing cached_tokens field is unknown, not zero. Token-priced work continues to require the necessary breakdown. If the service returns review_required or a more specific provider usage error, retain the operation identifier and contact support rather than create another paid company request.

Default queued/ongoing replies omit accounting and empty fields. Read the operation with ?view=details to inspect its quote, usage and settlement. Playground creates omit max_cost_usd, keeping route/quote binding and Idempotency-Key.

Image request errors

Errors contain a stable error.code, human-readable error.message, error.type and, where applicable, error.param. Keep X-Request-ID from the response for support; never send the API key. Unknown canonical model and alias return 400 model_not_found, not a catalog outage.

Restrictions of several routes are not merged into fictitious accepted combinations. Do not automatically repeat a paid POST after a timeout or ambiguous failure. Check operation status and keep the original idempotency key. Detailed internal configuration/credential errors are not returned to clients.