Die Beschreibungen der Operationen und Felder stammen aus dem Vertrag und sind auf Englisch.
/v1/audio/speechCreate speech
- Anmeldedaten
- API-Key
- Berechtigung
inference.invoke- SSE
- Kann streamen (Server-Sent Events)
- Request-Body
- Body bis 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.
Weiterlesen
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.eu.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"
}'Parameter
| Name | In | Beschreibung |
|---|---|---|
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. WeiterlesenGrammar ^[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. WeiterlesenSend 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. WeiterlesenA 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
modelstringPflichtThe 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}$
inputstringPflichtat least 1 characters
voicestringoptionalresponse_formatstringoptionalAudio container. Defaults to the provider's own default (mp3).
Erlaubte Werte:
"mp3""opus""aac""flac""wav""pcm"speednumberoptionalstreambooleanoptionalForwarded to the provider. The response body is relayed as it arrives either way.
Antworten
- 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.
Weiterlesen
The refusals of the hop (a fault of the platform) are listed in x-ccsio-hop-error-codes.
Fehlercodes: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:
Weiterlesen
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.
Weiterlesen
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.
Fehlercodes: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).
Fehlercodes: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.
Fehlercodes: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).
Weiterlesen
The router knows when a retry may succeed, but the API host does not relay a Retry-After header: retry with backoff.
Fehlercodes: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.
Fehlercodes: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.
Fehlercodes: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.
Fehlercodes: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.
Fehlercodes: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.
Fehlercodes:loop-detected
/v1/audio/transcriptionsCreate transcription
- Anmeldedaten
- API-Key
- Berechtigung
inference.invoke- Request-Body
- Body bis 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).
Weiterlesen
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.eu.ccsio.ai/v1/audio/transcriptions" \
-H "Authorization: Bearer $CCSIO_API_KEY" \
-F model=whisper-large-v3 \
-F [email protected]Parameter
| Name | In | Beschreibung |
|---|---|---|
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. WeiterlesenGrammar ^[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. WeiterlesenSend 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. WeiterlesenA 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 multipart/form-data
filestring (binary)PflichtThe audio file. The whole multipart body, file included, is capped at 26214400 bytes by default.
modelstringPflichtThe 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}$
languagestringoptionalpromptstringoptionalresponse_formatstringoptionalErlaubte Werte:
"json""text""srt""verbose_json""vtt"temperaturenumberoptionaltimestamp_granularities[]array of stringoptionalErlaubte Werte:
"word""segment"
Antworten
- 200
The transcript in the requested response_format.
Schema
one ofEines von
TranscriptionResponseobjectoptionalThe json response format, relayed from the provider.
textstringPflicht
TranscriptionVerboseResponseobjectoptionalThe 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).
taskstringoptionallanguagestringoptionaldurationone ofoptionalEines von
#1numberoptional#2stringoptional
textstringPflichtsegmentsarray of objectoptionalwordsarray of objectoptional
- 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.
Weiterlesen
The refusals of the hop (a fault of the platform) are listed in x-ccsio-hop-error-codes.
Fehlercodes: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:
Weiterlesen
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.
Weiterlesen
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.
Fehlercodes: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).
Fehlercodes: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.
Fehlercodes: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).
Weiterlesen
The router knows when a retry may succeed, but the API host does not relay a Retry-After header: retry with backoff.
Fehlercodes: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.
Fehlercodes: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.
Fehlercodes: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.
Fehlercodes: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.
Fehlercodes: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.
Fehlercodes:loop-detected
Erzeugt aus den Plattformverträgen beim Commit 5f833620.