Las descripciones de las operaciones y los campos son las del contrato, en inglés.
/v1/audio/speechCreate speech
- Credencial
- API key
- Permiso
inference.invoke- SSE
- Puede transmitir en streaming (server-sent events)
- Cuerpo de la solicitud
- Cuerpo de hasta 8 MiB
OpenAI-compatible text to speech through an audio-speech deployment. The provider's audio bytes are relayed as they arrive (never buffered whole) with the provider's Content-Type. The deployment endpoint is the full provider URL ending in /v1/audio/speech.
Leer más
A failure before the first audio byte is a JSON error (a 429 of the model server is a 429 provider-rate-limited, a timeout a 504 provider-timeout, anything else a 502 provider-error); a failure after it aborts the response instead of ending it cleanly. The usage fact is operation audio with the input_characters quantity (Unicode characters of input).
curl -N -X POST "https://api.latam.ccsio.ai/v1/audio/speech" \
-H "Authorization: Bearer $CCSIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kokoro-82m",
"input": "Welcome to the AI Control Plane.",
"voice": "af_heart",
"response_format": "wav"
}'Parámetros
| Nombre | En | Descripción |
|---|---|---|
X-Session-Idopcional | 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. Leer másGrammar ^[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-Idopcional | 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. Leer másSend 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-Idopcional | header | string The organization a signed-in person acts in, for a person who belongs to more than one. Leer másA 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). |
Cuerpo de la solicitud application/json
modelstringobligatorioThe 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}$
inputstringobligatorioat least 1 characters
voicestringopcionalresponse_formatstringopcionalAudio container. Defaults to the provider's own default (mp3).
Valores permitidos:
"mp3""opus""aac""flac""wav""pcm"speednumberopcionalstreambooleanopcionalForwarded to the provider. The response body is relayed as it arrives either way.
Respuestas
- 200
The synthesized audio.
- 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.
Leer más
The refusals of the hop (a fault of the platform) are listed in x-ccsio-hop-error-codes.
Códigos de error:decision-capability-mismatchinvalid-requestsession-id-invalid - 401
No credential, more than one, or one the platform does not accept: invalid-request (no credential, or both Authorization:
Leer más
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.
Leer más
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.
Códigos de error: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).
Códigos de error: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.
Códigos de error: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).
- 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).
Leer más
The router knows when a retry may succeed, but the API host does not relay a Retry-After header: retry with backoff.
Códigos de error: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.
Códigos de error: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.
Códigos de error: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.
Códigos de error: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.
Códigos de error: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.
Códigos de error:loop-detected
/v1/audio/transcriptionsCreate transcription
- Credencial
- API key
- Permiso
inference.invoke- Cuerpo de la solicitud
- Cuerpo de hasta 25 MiB
OpenAI-compatible speech to text through an audio-transcriptions deployment. The multipart body is forwarded to the provider byte for byte with its Content-Type (boundary included) and the provider's JSON or text answer is relayed with the provider's Content-Type (text/plain when it names none).
Leer más
The deployment endpoint is the full provider URL ending in /v1/audio/transcriptions. The usage fact is operation audio with the audio_seconds quantity when the provider reports a duration (verbose_json), otherwise no quantity with measurement unknown and reason final_usage_missing. A multipart body without exactly one plain model field is refused with 400 invalid-request. A failure of the model server is a JSON error (429 provider-rate-limited, 504 provider-timeout, anything else 502 provider-error).
curl -X POST "https://api.latam.ccsio.ai/v1/audio/transcriptions" \
-H "Authorization: Bearer $CCSIO_API_KEY" \
-F model=whisper-large-v3 \
-F [email protected]Parámetros
| Nombre | En | Descripción |
|---|---|---|
X-Session-Idopcional | 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. Leer másGrammar ^[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-Idopcional | 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. Leer másSend 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-Idopcional | header | string The organization a signed-in person acts in, for a person who belongs to more than one. Leer másA 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). |
Cuerpo de la solicitud multipart/form-data
filestring (binary)obligatorioThe audio file. The whole multipart body, file included, is capped at 26214400 bytes by default.
modelstringobligatorioThe 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}$
languagestringopcionalpromptstringopcionalresponse_formatstringopcionalValores permitidos:
"json""text""srt""verbose_json""vtt"temperaturenumberopcionaltimestamp_granularities[]array of stringopcionalValores permitidos:
"word""segment"
Respuestas
- 200
The transcript in the requested response_format.
Esquema
one ofUno de
TranscriptionResponseobjectopcionalThe json response format, relayed from the provider.
textstringobligatorio
TranscriptionVerboseResponseobjectopcionalThe verbose_json response format, relayed from the provider. duration (seconds) is the metered audio_seconds quantity; when a provider omits it the usage fact is recorded as unknown (final_usage_missing).
taskstringopcionallanguagestringopcionaldurationone ofopcionalUno de
#1numberopcional#2stringopcional
textstringobligatoriosegmentsarray of objectopcionalwordsarray of objectopcional
- 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.
Leer más
The refusals of the hop (a fault of the platform) are listed in x-ccsio-hop-error-codes.
Códigos de error:decision-capability-mismatchinvalid-requestsession-id-invalid - 401
No credential, more than one, or one the platform does not accept: invalid-request (no credential, or both Authorization:
Leer más
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.
Leer más
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.
Códigos de error: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).
Códigos de error: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.
Códigos de error: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).
- 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).
Leer más
The router knows when a retry may succeed, but the API host does not relay a Retry-After header: retry with backoff.
Códigos de error: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.
Códigos de error: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.
Códigos de error: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.
Códigos de error: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.
Códigos de error: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.
Códigos de error:loop-detected
Generado a partir de los contratos de la plataforma en el commit 5f833620.