千问办公企业旗舰版开发者文档:使用指南。
会话服务使用指南
认证方式见APP开发者文档 → 认证接入。
开始前
会话接口前缀为 /api/openapi/app/v1/sessions。最小请求示例见“调用流程”,事件游标与重连见“事件与恢复”。
一次任务的调用顺序
| 步骤 | 接口 | 调用要点 |
|---|---|---|
| 选择档位 | GET /api/openapi/app/v1/sessions/session-modes | 使用返回的可用档位与默认值,不写死模型 ID;运行依赖不可用时返回服务错误 |
| 创建会话 | POST /api/openapi/app/v1/sessions | 提交 initial_prompt;沙箱就绪后自动开始首轮,不再重复发送同一条指令 |
| 接收进度 | GET /api/openapi/app/v1/sessions/{session_id}/events/stream | 订阅 SSE,保存游标;事件字段及恢复方法见“事件与恢复” |
| 回应提问 | POST /api/openapi/app/v1/sessions/{session_id}/question-response | 会话等待用户输入时,按实际 pending_action 与接口字段回应 |
| 查看结果 | GET /api/openapi/app/v1/sessions/{session_id}/output | 结合会话状态、Turn 与执行事件判断结果,创建请求成功不等于任务完成 |
输入框语音输入
语音输入可在创建会话前使用,不需要 session_id,也不会创建会话或自动发送指令。
- 通过“实时语音转写”建立 WebSocket,上传单声道 16 kHz PCM16LE 二进制音频,按 index 替换临时预览。
- 停止采集后发送一次 finish,继续等待全部 final 和 finished。提前断线或失败时丢弃局部结果。
- 将完整且非空的转写原文、光标前后上下文和当前模型档位传给“润色语音转写”。polished=false 时使用完整原文。
- 确认输入框版本和当前会话仍与录音开始时一致,再插入 text,等待用户确认发送。
继续会话与管理队列
向 POST /api/openapi/app/v1/sessions/{session_id}/prompt 提交后续指令。会话忙碌时可能排队,使用 prompt-queue 查询、编辑与删除接口管理尚未执行的指令。取消当前执行使用 cancel,撤回排队指令使用删除队列项接口,两者作用不同。
断线后恢复与历史读取
浏览器关闭或 SSE 断开不等于服务端任务失败。重新连接后查询会话状态,并使用已保存游标读取事件、恢复订阅;不要用重复创建会话代替恢复。查询 turns、单个 Turn 与 output 可查看执行历史和产物,继续沿用当前历史加载方式。
网页预览与浏览器窗口
产物事件带有沙箱 ID 时,使用 GET /api/openapi/app/v1/sessions/sandboxes/{sandbox_id}/info 查询当前状态和最新桌面地址。保留完整沙箱 ID,按返回状态决定是否显示窗口;具体字段、权限和错误处理见“查询沙箱状态与桌面地址”。
写请求重试
创建会话或发送指令超时,不能据此认定服务端没有接纳请求。保留已取得的会话、指令和游标标识,先查询状态,再按单接口契约决定下一步;不假定所有写接口都支持 Idempotency-Key。只有当前用户有权访问的会话才可查询和操作。
会话整理与子会话
使用会话 PATCH 修改名称,使用 /{session_id}/pin 显式置顶或取消置顶。侧栏可组合 pinned 与 recent:前者只含置顶项,后者只含未置顶项;计划任务按分组显示最新主会话,组置顶对后续执行有效。普通 sessions 列表保持原契约。
需要完整读取父会话的直接子会话时,调用 /{session_id}/children 并按 cursor/limit 分页。所有读取及变更都检查当前IAM用户归属。批量清理某计划产生的会话,使用计划任务下的“删除计划会话分组”;它不暂停或删除计划。