服務端事件

本文介紹 Qwen-TTS-Realtime API 的服務端事件。

相關文檔：即時語音合成-通義千問。

error

不論是遇到用戶端錯誤還是服務端錯誤，服務端都會響應該事件。

參數	類型	說明
type	string	事件類型，該事件下固定為`error`。
error	object	錯誤的詳細資料。
error.type	string	錯誤類型。
error.code	string	錯誤碼。
error.message	string	錯誤資訊。
error.param	string	與錯誤相關的參數，如`session.voice`。

{
  "event_id": "event_B2uoU7VOt1AAITsPRPH9n",
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_value",
    "message": "Invalid value: 'qwen-tts'. Supported values are: 'Qwen2.5-tts'.",
    "param": "session.input_audio_transcription.model",
    "event_id": "event_123"
  }
}

session.created

用戶端串連到服務端後，響應的第一個事件，該事件返回時會攜帶服務端對此次串連的預設配置資訊。

參數	類型	說明
type	string	事件類型，該事件下固定為`session.created`。
session	object	session配置。
session.id	string	session 的唯一標識。
session.object	string	session 的服務名。
session.mode	string	模型響應模式設定。
session.model	string	使用的模型。
session.voice	string	模型產生音訊音色。
session.response_format	string	模型輸出音訊格式，當前只支援設定為"pcm"。
session.sample_rate	integer	模型輸出音訊採樣率，當前只支援設定為24000。

{
  "event_id": "event_xxx",
  "type": "session.created",
  "session": {
    "object": "realtime.session",
    "mode": "server_commit",
    "model": "qwen-tts-realtime",
    "voice": "Cherry",
    "response_format": "pcm",
    "sample_rate": 24000,
    "id": "sess_xxx"
  }
}

session.updated

接收到用戶端的session.update請求並正確處理後返回。如果出現錯誤，則直接返回error事件。

參數	類型	說明
type	string	事件類型，該事件下固定為`session.updated`。
session	object	session配置。
session.id	string	session 的唯一標識。
session.object	string	session 的服務名。
session.mode	string	模型輸出模式設定。
session.model	string	使用的模型。
session.voice	string	模型產生音訊音色。
session.language_type	string	指定合成音訊語種，預設為 `Auto`。 `Auto`：適用無法確定文本的語種或文本包含多種語言的情境，模型會自動為文本中的不同語言片段匹配各自的發音，但無法保證發音完全精準。指定語種：適用於文本為單一語種的情境，此時指定為具體語種，能顯著提升合成品質，效果通常優於 `Auto`。可選值包括： `Chinese` `English` `German` `Italian` `Portuguese` `Spanish` `Japanese` `Korean` `French` `Russian`
session.response_format	string	模型輸出音訊格式，當前只支援設定為"pcm"。
session.sample_rate	integer	模型輸出音訊採樣率，當前只支援設定為24000。

{
  "event_id": "event_xxx",
  "type": "session.updated",
  "session": {
    "id": "sess_xxx",
    "object": "realtime.session",
    "model": "qwen-tts-realtime",
    "voice": "Cherry",
    "language_type": "Chinese",
    "mode": "commit",
    "response_format": "pcm",
    "sample_rate": 24000
  }
}

input_text_buffer.committed

用戶端發送input_text_buffer.commit事件後，服務端的響應事件。

參數	類型	說明
event_id	string	本次事件的標識。
type	string	事件類型，該事件下固定為`input_text_buffer.committed`。
item_id	string	將建立的使用者訊息項的 ID。

{
  "event_id": "event_FC6MA88wS2oEeXkPvWsxX",
  "type": "input_text_buffer.committed",
  "item_id": ""
}

input_text_buffer.cleared

用戶端發送input_audio_buffer.clear事件後，服務端的響應事件。

參數	類型	說明
event_id	string	本次事件的標識。
type	string	事件類型，該事件下固定為`input_text_buffer.cleared`。

{
    "event_id": "event_1122",
    "type": "input_text_buffer.cleared"
}

response.created

服務端產生新的模型響應時，返回該事件。

參數	類型	說明
type	string	該事件下固定為`response.created`。
event_id	string	本次事件的標識。
response	object	響應對象。
response.id	string	響應的唯一 ID。
response.object	string	物件類型，此事件下固定為`realtime.response`。
response.status	string	響應的最終狀態，取值範圍 [completed, failed, in_progress, or incomplete]。
response.voice	string	模型產生音訊音色。
response.output	array	此事件下目前為空白。

{
  "event_id": "event_IMnLqDvG6Ahhk7sWV2uOs",
  "type": "response.created",
  "response": {
    "id": "resp_USvBwHktHcz76r6GaIJUV",
    "object": "realtime.response",
    "conversation_id": "",
    "status": "in_progress",
    "voice": "Cherry",
    "output": []
  }
}

response.output_item.added

當新的item項需要輸出時，服務端返回此事件。

參數	類型	說明
type	string	固定為`response.output_item.added`。
response_id	string	可關聯同一個response的所有輸出。
output_index	integer	response中輸出項的索引, 目前固定為0。
item	object	輸出項資訊。
item.id	string	輸出項的唯一ID。
item.object	string	始終為 `realtime.item` 。
item.status	string	輸出項的狀態。
item.content	array	訊息的內容。

{
  "event_id": "event_INDGnGNulaXCrStd9ZM5X",
  "type": "response.output_item.added",
  "response_id": "resp_USvBwHktHcz76r6GaIJUV",
  "output_index": 0,
  "item": {
    "id": "item_FIrYGaNVK3rbIZqeY4QjM",
    "object": "realtime.item",
    "type": "message",
    "status": "in_progress",
    "role": "assistant",
    "content": []
  }
}

response.content_part.added

當新的內容項需要輸出時，服務端返回此事件。

參數	類型	說明
type	string	固定為`response.content_part.added`。
response_id	string	響應的ID。
item_id	string	訊息項ID。
output_index	integer	響應輸出項的索引, 目前固定為0。
content_index	integer	響應輸出項中內部部分的索引, 目前固定為0。
part	object	已完成的內容部分。
part.type	string	內容部分的類型。
part.text	string	內容部分的文本。

{
  "event_id": "event_DigZ95MWN36YYyyjcENoq",
  "type": "response.content_part.added",
  "response_id": "resp_USvBwHktHcz76r6GaIJUV",
  "item_id": "item_FIrYGaNVK3rbIZqeY4QjM",
  "output_index": 0,
  "content_index": 0,
  "part": {
    "type": "audio",
    "text": ""
  }
}

response.audio.delta

當模型增量產生新的audio資料時，系統會返回伺服器 response.audio.delta 事件。

參數	類型	說明
type	string	固定為`response.audio.delta`。
response_id	string	可以關聯同一個response的所有輸出。
item_id	string	訊息項id，可以關聯同一個訊息item。
output_index	integer	response中輸出項的索引, 目前固定為0。
content_index	integer	response中輸出項中內部部分的索引, 目前固定為0。
delta	string	模型增量輸出的audio資料，使用Base64編碼。

{
  "event_id": "event_B1osWMZBtrEQbiIwW0qHQ",
  "type": "response.audio.delta",
  "response_id": "resp_B1osWTzBb8hO0WsELHgVP",
  "item_id": "item_B1osWH81fXDoyim1T5fsF",
  "output_index": 0,
  "content_index": 0,
  "delta": "base64 audio"
}

response.content_part.done

當新的內容項輸出完成時，服務端返回此事件。

參數	類型	說明
type	string	固定為`response.content_part.done`。
response_id	string	響應的ID。
item_id	string	訊息項ID。
output_index	integer	響應輸出項的索引, 目前固定為0。
content_index	integer	響應輸出項中內部部分的索引, 目前固定為0。
part	object	已完成的內容部分。
part.type	string	內容部分的類型。
part.text	string	內容部分的文本。

{
  "event_id": "event_Vo2YUjlYQJ4colH8nVzkU",
  "type": "response.content_part.done",
  "response_id": "resp_USvBwHktHcz76r6GaIJUV",
  "item_id": "item_FIrYGaNVK3rbIZqeY4QjM",
  "output_index": 0,
  "content_index": 0,
  "part": {
    "type": "audio",
    "text": ""
  }
}

response.output_item.done

當新的item輸出完成時，服務端返回此事件。

參數	類型	說明
type	string	固定為`response.output_item.done`。
response_id	string	響應的ID。
output_index	integer	response中輸出項的索引, 目前固定為0。
item	object	輸出項資訊。
item.id	string	輸出項的唯一ID。
item.object	string	始終為 `realtime.item` 。
item.status	string	輸出項的狀態。
item.content	array	訊息的內容。

{
  "event_id": "event_LO6SJRKIQ9NBayyYB8a1A",
  "type": "response.output_item.done",
  "response_id": "resp_USvBwHktHcz76r6GaIJUV",
  "output_index": 0,
  "item": {
    "id": "item_FIrYGaNVK3rbIZqeY4QjM",
    "object": "realtime.item",
    "type": "message",
    "status": "completed",
    "role": "assistant",
    "content": [
      {
        "type": "audio",
        "text": ""
      }
    ]
  }
}

response.audio.done

當模型產生audio資料完成時，系統會返回伺服器 response.audio.done 事件。

參數	類型	說明
type	string	固定為`response.audio.done`。
response_id	string	response_id，可以關聯同一個resposne的所有輸出。
item_id	string	訊息項id，可以關聯同一個訊息item。
output_index	integer	response中輸出項的索引, 目前固定為0。
content_index	integer	response中輸出項中內部部分的索引, 目前固定為0。

{
  "event_id": "event_LZaOHPzXYMUXGBcVkBmKX",
  "type": "response.audio.done",
  "response_id": "resp_USvBwHktHcz76r6GaIJUV",
  "item_id": "item_FIrYGaNVK3rbIZqeY4QjM",
  "output_index": 0,
  "content_index": 0
}

response.done

當響應產生完成時，服務端會返回此事件。該事件中包含的 Response 對象將包含 Response 中的所有輸出項，但不包括已返回的原始音頻資料。

參數	類型	說明
type	string	固定為`response.done`。
response	object	響應對象。
response.id	string	響應的唯一 ID。
response.object	string	物件類型，此事件下固定為`realtime.response`。
response.output	array	響應的輸出。
response.usage	object	本次語音合成計費資訊。
response.usage.characters	integer	Qwen3-TTS Realtime計費字元數。
response.usage.total_tokens	integer	Qwen-TTS Realtime輸入和輸出（合成的音頻）內容總長度（Token）。
response.usage.input_tokens	integer	Qwen-TTS Realtime輸入內容總長度（Token）。
response.usage.output_tokens	integer	Qwen-TTS Realtime輸出內容總長度（Token）。
response.usage.input_tokens_details	integer	Qwen-TTS Realtime輸入內容長度（Token）詳情。
response.usage.input_tokens_details.text_tokens	integer	Qwen-TTS Realtime輸入常值內容總長度（Token）。
response.usage.output_tokens_details	integer	Qwen-TTS Realtime輸出內容長度（Token）詳情。
response.usage.output_tokens_details.text_tokens	integer	Qwen-TTS Realtime輸出常值內容總長度（Token）。
response.usage.output_tokens_details.audio_tokens	integer	Qwen-TTS Realtime輸出音頻內容總長度（Token）。音頻轉換為 Token 的規則：每1秒的音頻對應 50個 Token 。若音頻時間長度不足1秒，則按 50個 Token 計算。

Qwen3-TTS Realtime

{
    "event_id": "event_Aemy83XqHFFDDSeJIDn6N",
    "type": "response.done",
    "response": {
        "id": "resp_LFeR42yXZ9SxUAeXjmyTz",
        "object": "realtime.response",
        "conversation_id": "",
        "status": "completed",
        "modalities": [
            "text",
            "audio"
        ],
        "voice": "Cherry",
        "output": [
            {
                "id": "item_Ae1lv2XmRljRSG96L8Zm1",
                "object": "realtime.item",
                "type": "message",
                "status": "completed",
                "role": "assistant",
                "content": [
                    {
                        "type": "audio",
                        "transcript": ""
                    }
                ]
            }
        ],
        "usage": {
            "characters": 25
        }
    }
}

Qwen-TTS Realtime

{
  "event_id": "event_xxx",
  "type": "response.done",
  "response": {
    "id": "resp_xxx",
    "object": "realtime.response",
    "conversation_id": "",
    "status": "completed",
    "modalities": [
      "text",
      "audio"
    ],
    "voice": "Cherry",
    "output": [
      {
        "id": "item_FIrYGaNVK3rbIZqeY4QjM",
        "object": "realtime.item",
        "type": "message",
        "status": "completed",
        "role": "assistant",
        "content": [
          {
            "type": "audio",
            "transcript": ""
          }
        ]
      }
    ],
    "usage": {
      "total_tokens": 67,
      "input_tokens": 3,
      "output_tokens": 64,
      "input_tokens_details": {
        "text_tokens": 3
      },
      "output_tokens_details": {
        "text_tokens": 0,
        "audio_tokens": 64
      }
    }
  }
}

session.finished

當所有響應產生完成時，服務端會返回此事件。

參數	類型	說明
type	string	固定為`session.finished`。
event_id	object	本次事件的標識。

{
  "event_id": "event_2239",
  "type": "session.finished"
}