Validate and update a hosted agent's STT, model, and TTS selections

The target agent defines the authenticated workspace. Select platform-managed components by provider/model/voice fields, or bind a component to an already-created hosted-AI credential by its ID in component_credential_bindings. The binding is a reference only: upload a BYOK secret through the separate write-only hosted-ai-credentials API; this route never accepts or returns secret material. Supplying languages and optional sparse language_profiles is an explicit publication: all effective profiles are constructible and credential-owned before an immutable version is stored for admission. audio_environment is a separately version-pinned outgoing-only ambience track, shared across language profiles and independent of caller STT; its optional runtime failure never replaces the selected voice/language or prevents the core call. Draft profile edits never alter existing calls or published sessions.

patch/v1/agents/{agent_id}/voice-stack

Request

  • Base URL: https://api.skysay.ai
  • URL: https://api.skysay.ai/v1/agents/{agent_id}/voice-stack
  • Auth: none declared

Path parameters

agent_idstring required

Request body

begin_messagestring

Legacy alias for first_message.

component_credential_bindingsobject

Optional stt/llm/tts map to existing hosted-AI credential IDs (or null to use platform-managed selection). References are validated; secret upload is a separate write-only API.

first_messagestring
languagestring
language_profile_revisioninteger

Optional optimistic-concurrency revision returned by GET. A stale value returns conflict; reload before retrying.

languagesstring[]

When supplied this replaces the selected language set. An engine without a language axis (see voice_frontend and the agent-catalog conversation_engines block) REFUSES this field with 400 rather than accepting and dropping it.

system_promptstring
voice_frontend'cascade' | 'gpt_live' | 'gemini_live'

Optional conversation engine. Omitted or cascade is STT/LLM/TTS. gpt_live selects GPT-Live-1. GET still returns transcriber, model, and voice as an OpenAI compatibility projection. Each engine declares whether it has a language axis; a voice-to-voice engine does not, and this route then refuses languages, language_profiles and follow_caller with a 400 naming the field and the engine. Read has_language_axis from the agent-catalog conversation_engines block rather than assuming it from the id.

Response

Updated safe voice-stack projection

agent_idstring required
costobject required
first_messagestring
languagestring required
latencyobject required
modelobject required
organization_idstring required
project_idstring required
selectableboolean required
system_promptstring
transcriberobject required
voiceobject required

The stored TTS selection as the agent catalog projects it, including delivery_control (voice_settings, instruction, speed or unsupported): whether a voice_polish.delivery profile changes this voice's audio, and delivery_profiles: the exact value each profile resolves to on this engine (empty for unsupported), both read from the packaged delivery table.

voice_frontend'cascade' | 'gpt_live' | 'gemini_live'

The conversation engine; cascade is the default. Always present on GET; omitted on older rows means cascade. Whether this engine has a language axis is declared in the agent-catalog conversation_engines block (has_language_axis).

voice_labelstring
warningsstring[] required

Changes

No recorded changes to this operation across all 1 revision of this API.