创建用于实时语音、文本交互和后台任务事件的 Conversation。
Realtime 目前为 Beta 功能，接口定义、事件结构和行为可能发生变化。请关注文档更新，并在生产环境使用前完成兼容性验证。
POST /api/v1/forward/realtime/conversations
请求头
| Header | 是否必填 | 说明 |
|---|---|---|
| Authorization | 是 | Bearer <PAT 或 SAT> |
| Content-Type | 是 | application/json |
| Idempotency-Key | 是 | 应用生成的创建操作标识，1～256 字节，无首尾空白，推荐 UUID。同一操作重试复用原值和请求体。 |
请求体参数
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| identity_id | string | 是 | 当前认证范围内可访问且已启用的 Identity ID，1～128 个字符，无首尾空白或控制字符。 |
| template_id | string | 是 | 当前认证范围内可访问的 Template ID，1～128 个字符，无首尾空白或控制字符。 |
| title | string 或 null | 否 | 默认 null；去除首尾空白后为 1～256 个字符，不接受控制字符。 |
| metadata | object 或 null | 否 | 默认 {}，null 按 {} 处理；规范化后的存储文本不超过 16 KiB，不接受 U+0000。 |
| config | object | 否 | Conversation 的 Realtime 配置。省略时由服务端解析默认配置；不接受 null。 |
| config.audio | object | 否 | 音频配置。 |
| config.audio.output | object | 否 | 输出音频配置。 |
| config.audio.output.voice | string | 否 | 预置音色标识，只接受下表中的值。创建后固定，不支持修改。 |
预置音色
| voice | 名称 |
|---|---|
longanqian | 默认 |
longanlingxin | 龙安灵心 |
longanlingxi | 龙安灵希 |
longanxiaoxin | 龙安小昕 |
longanlufeng | 龙安鲁风 |
示例请求
示例响应
HTTP 201 Created
响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | Conversation ID。 |
| type | string | 固定为 voice.conversation。 |
| status | string | 创建成功时为 ready。 |
| title | string 或 null | 会话标题。 |
| metadata | object | 业务元数据。 |
| config | object | 服务端解析并固化后的完整有效配置。 |
| config.audio.output.voice | string | Conversation 固化的输出音色。 |
| created_at | string | 创建时间，RFC 3339。 |
| updated_at | string | 更新时间，RFC 3339。 |
幂等重试
- 相同
Idempotency-Key和相同请求体会重放首次创建结果。 - 重放响应包含
Idempotency-Replayed: true。 - 相同
Idempotency-Key对应不同请求体时返回409 idempotency_conflict。 - 首次请求仍在处理时返回
409 idempotency_key_in_progress，重试间隔见Retry-After。
错误
| HTTP | Code | 触发条件 |
|---|---|---|
| 400 | invalid_request、invalid_identity_id、invalid_template_id、invalid_title、invalid_metadata | 请求参数无效。 |
| 400 | invalid_voice | config.audio.output.voice 不受支持。 |
| 400 | invalid_idempotency_key | 幂等 Header 缺失或无效。 |
| 401 | authentication_required、入口层 TOKEN_INVALID | PAT 或 SAT 无效、已过期，或直接使用了 Service Account Key。 |
| 403 | permission_error、identity_mismatch | SAT 未绑定可用的 Workspace，或 Identity 级 SAT 指定了其他 Identity。 |
| 404 | identity_not_found | 当前认证范围内未找到 Identity。 |
| 409 | idempotency_conflict | 同一 key 不能用于不同请求。 |
| 409 | idempotency_key_in_progress | 同一 key 的请求仍在处理，重试间隔见 Retry-After。 |
| 409 | conversation_not_ready、conversation_initialization_conflict | 会话未就绪或初始化冲突。 |
| 422 | identity_disabled | Identity 已禁用。 |
| 422 | conversation_initialization_failed | 会话初始化失败。 |
| 500 | conversation_persistence_error、conversation_state_invalid、template_config_read_failed、internal_error | 服务内部错误。 |
| 502 | forward_unavailable、forward_protocol_error | 依赖服务异常。 |
| 503 | idempotency_unavailable | 服务暂不可用。 |