The descriptions of the operations and fields are the contract’s own, in English.
/v1/images/generationsCreate images
- Credential
- API key
- Permission
inference.invoke- Request body
- Body up to 8 MiB
OpenAI-compatible image generation (the Images generations shape) through an image-generations deployment. The JSON body is relayed to the model server with only model rewritten, and the server's JSON answer is relayed; the operation never streams. Image edits and image variations are not served.
Read more
The usage fact is operation image with the images quantity (the number of entries of the answer's data array); an attempt that fails or does not finish carries no quantity, with measurement unknown and reason final_usage_missing. A body without a model, or with a prompt that is missing, empty or not a string, is refused with 400 invalid-request by the platform. Of the model server's refusals three reach the caller: a 400 as 400 provider-bad-request and a 413 (input_too_long) as 413 provider-input-too-long, both with the model server's own message (bounded and scrubbed), and a 429 (busy) as 429 provider-rate-limited. Its 404, its 503 (loading), any other status and an answer that is not a JSON object are a 502 provider-error; a timeout is a 504 provider-timeout.
curl -X POST "https://api.latam.ccsio.ai/v1/images/generations" \
-H "Authorization: Bearer $CCSIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "flux.2-klein-4b",
"prompt": "A lighthouse at dawn, watercolor",
"size": "1024x1024",
"response_format": "b64_json"
}'Parameters
| Name | In | Description |
|---|---|---|
X-Session-Idoptional | header | string Optional client-provided session label, accepted on every /v1 operation. It groups the caller's requests in the request log (the session_id of the usage facts and of the request-log reads); it is a label only, never an identity, and is never used for authorization or tenancy. Read moreGrammar ^[A-Za-z0-9._:-]{1,128}$, given at most once: anything else (empty, longer than 128 characters, other characters, repeated) is refused 400 session-id-invalid in the OpenAI error shape, after the credential, billing, permission and body-size checks and before the request is decoded. |
X-Team-Idoptional | header | string The team the call acts for. Send it when the caller holds roles in more than one team: the platform cannot pick one, and without it the call is refused with 403 policy-denied. Read moreSend it also to act for one team on purpose: the models that are listed and may be called then follow that team's entitlements, and the quota and the usage are attributed to it. The team must be one the caller is an active member of: a team the caller does not belong to, an archived team and a malformed identifier are refused with 403 team-not-selectable. A caller whose roles are organization-wide needs no team. |
X-Organization-Idoptional | header | string The organization a signed-in person acts in, for a person who belongs to more than one. Read moreA person with exactly one organization needs no header; a person with several is refused with 403 organization-selection-required without it, and a value that names an organization the person holds no active membership in is refused with 403 organization-not-selectable. An API key carries its own organization and ignores the header, except a platform administrator's credential and a platform operator signed in at the backoffice, who may name any existing organization (an operator who names none holds the platform context, which these operations refuse with 403 organization-selection-required). The header selects among memberships that already exist: it never grants one, and the residency of the organization it selects must be the plane's own (403 residency-mismatch). |
Request body application/json
modelstringrequiredThe broad C0 model_ref vocabulary. Gateway routing additionally requires the stricter C7 identifier pattern ^[a-z][a-z0-9._-]{0,63}$; a C0-valid value that is not C7-routeable is refused with 400.
pattern ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$
promptstringrequiredThe text to draw. It must not be empty.
at least 1 characters
nintegeroptionalHow many images to generate.
sizestringoptionalWIDTHxHEIGHT in pixels, for example 1024x1024.
pattern ^[0-9]+x[0-9]+$
seedintegeroptionalA seed that makes the generation repeatable.
response_formatstringoptionalThe only format the model servers serve: the image inline as base64.
Allowed values:
"b64_json"
Responses
- 200
The generated images, base64-encoded PNG files.
Schema
ImageGenerationResponsecreatedintegerrequiredUnix time in seconds.
dataarray of GeneratedImagerequiredb64_jsonstringrequiredThe PNG file, base64-encoded.
- 400
The request is refused before it is dispatched, or the model server refused it. invalid-request: a body that is not valid JSON (or not multipart/form-data with a boundary), a member of the wrong type, a missing or empty model, a chat request with no messages, an embeddings or speech request with no input (speech: not a string), an images request with no prompt (not a string), a decisions request with no state, with questions that are not a non-empty object, a message content that is not a string, null or an array, a transcription whose multipart body does not carry exactly one plain model field. session-id-invalid: a malformed or repeated X-Session-Id. provider-bad-request: images and decisions only, the model server refused the request with 400 and the message is its own, bounded and scrubbed of any credential.
Read more
The refusals of the hop (a fault of the platform) are listed in x-ccsio-hop-error-codes.
Error codes:decision-capability-mismatchdecision-stream-mismatchinvalid-requestprovider-bad-requestsession-id-invalid - 401
No credential, more than one, or one the platform does not accept: invalid-request (no credential, or both Authorization:
Read more
Bearer and x-api-key), api-key-invalid, api-key-unknown, api-key-revoked, api-key-expired, the refusals of a bearer token (token-malformed, token-algorithm-unsupported, token-signature-invalid, token-issuer-mismatch, token-audience-mismatch, token-expired, token-not-yet-valid, token-claim-invalid), the trust in its issuer (issuer-untrusted, issuer-resolution-unknown, issuer-residency-mismatch, jwks-unavailable, jwks-invalid, jwks-key-not-found), a person with no account on this plane (identity-not-provisioned, organization-not-found) and, for a backoffice operator's token, staff-token-inactive, staff-not-operator and staff-directory-unavailable. The complete list is x-ccsio-boundary-error-codes. A 401 can also be a refusal of the hop between core and the router (missing-verified-context, invalid-verified-context, context-signature-*): that is a fault of the platform, not of the credential. Supply exactly one credential.
- 402
payment-required: the organization has no active subscription.
Read more
The call is refused before its body is read; platform operators are exempt. credits-exhausted: the model is served from a third-party provider, the plane charges such models against prepaid credits, and the organization's balance is zero or negative; the organization tops up (or an operator credits it) and the next request is admitted. Streams already running finish. The model stays listed by GET /v1/models, which never answers credits-exhausted (and answers payment-required like every operation). The error type is invalid_request_error.
Error codes:credits-exhausted - 403
Refused by the platform after the credential was accepted: policy-denied (no role of the caller holds the permission, a personal API key whose owner lacks it, an acting team that is ambiguous or no longer authorized), tenant-mismatch (X-Tenant names another organization), team-not-selectable (X-Team-Id names a team the caller cannot act for), organization-inactive and the other states of the organization (organization-provisioning, organization-suspended, organization-disabled, organization-deleted), user-disabled, organization-selection-required (a person who belongs to several organizations and sent no X-Organization-Id, or a platform operator who selected none), organization-not-selectable, no-active-organization-membership, entitlement-denied (the organization or the acting team is not entitled to the model, which includes a model that does not exist), residency-mismatch (the organization, or the deployment's residency, does not match the plane's) or external-model-not-available (the model is served from a third-party provider and the organization is not admitted to such models: while a payment provider is configured and credits are not enabled only an organization that is billing-exempt or billed by contract is admitted; on a plane where credits are enabled the gate is credits-exhausted or model-not-priced instead, and this refusal is not answered; the model stays listed by GET /v1/models).
Error codes:entitlement-deniedexternal-model-not-availableorganization-inactiveresidency-mismatch - 404
model-not-found: the organization is entitled to the model but no active deployment serves it with the operation's capability. A chat or embeddings model on an audio route, and an audio model on any other route, is refused this way. A path under /v1/ that nothing claims is also a 404, with the code not-found.
Error codes:model-not-found - 405
method-not-allowed: the path is claimed but the request method is not allowed. The Allow header lists the methods the path accepts.
- 413
request-body-too-large: the request body exceeds the operation's cap (8388608 bytes for a JSON body, 26214400 for an audio transcription upload); answered after authentication and authorization (an unauthenticated or unauthorized request is refused first, without its body being read).
Error codes:provider-input-too-long - 429
A concurrency or rate limit of the organization, the team, the model or the deployment was reached (organization-concurrency-exceeded, team-concurrency-exceeded, model-concurrency-exceeded, deployment-concurrency-exceeded, rate-limit-exceeded; entitlement-denied, which the router answers as a defense in depth when the model is outside the entitlements the hop carries and core has already checked), or the model server rate-limited the call (provider-rate-limited: audio, images, decisions, and chat with a stream; chat without a stream answers that case 503 provider-unavailable).
Read more
The router knows when a retry may succeed, but the API host does not relay a Retry-After header: retry with backoff.
Error codes:deployment-concurrency-exceededentitlement-deniedmodel-concurrency-exceededorganization-concurrency-exceededprovider-rate-limitedrate-limit-exceededteam-concurrency-exceeded - 500
A failure of the platform, rendered without internal cause details: internal-error (core could not decide or load what the request needs), quota-store-unavailable (the router could not read its quota store, so the request was refused) and, for a fault of the hop, unsupported-protocol-version, deployment-not-active, tenant-mismatch, model-pin-mismatch, placement-mismatch, bundle-tenant-mismatch and upstream-endpoint-invalid.
Error codes:internal-errorquota-store-unavailable - 502
The model server failed or its answer could not be used: provider-error (it answered an error status other than a 429 that this operation passes on, or nothing usable; its own error body is never relayed), provider-credential-rejected (it answered 401 or 403 to the API key stored for the model's deployment), forwarder-failed (core could not reach the router), internal-hop-body (the router could not read the body core sent). The stored key never appears in any answer.
Error codes:forwarder-failedprovider-credential-rejectedprovider-error - 503
provider-unavailable (OpenAI shape): no deployment of the model is currently healthy, or the one deployment there is failed this very request with a 429, a 5xx or an answer that was not one (on chat without a stream, and on embeddings and non-streaming Responses, where it is rendered in the kernel envelope). model-not-priced (OpenAI shape, type server_error): the model is served from a third-party provider, the plane charges such models against prepaid credits and no price is set for the model in the plane's currency; nothing is dispatched. router-not-configured (the platform kernel envelope, the one deliberate exception of core): this deployment has no inference router at all.
Error codes:model-not-pricedprovider-unavailablerouter-not-configured - 504
provider-timeout: the dispatch deadline passed before the model server answered. Audio, images, decisions and chat; embeddings and Responses never answer 504.
Error codes:provider-timeout - 508
loop-detected: the request carried the X-Ccsio-Egress header, which the platform's own egress adds to every request it makes to a model provider. It is answered when a provider connection points back at the platform's own API; an ordinary client never meets it.
Error codes:loop-detected
Generated from the platform contracts at commit 5f833620.