Skip to main content

使用指南

千问办公企业旗舰版开发者文档:使用指南。

会话服务使用指南

认证方式见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;具体请求字段及错误码以各接口页为准。创建请求中的 files 只引用已存储附件,不负责上传文件。文件上传步骤见文件模块“使用指南”;按 PromptFile 参数定义引用文件路径,不使用上传会话 ID 替代文件路径。

输入框语音输入

语音输入可在创建会话前使用,不需要 session_id,也不会创建会话或自动发送指令。
  1. 通过“实时语音转写”建立 WebSocket,上传单声道 16 kHz PCM16LE 二进制音频,按 index 替换临时预览。
  2. 停止采集后发送一次 finish,继续等待全部 final 和 finished。提前断线或失败时丢弃局部结果。
  3. 将完整且非空的转写原文、光标前后上下文和当前模型档位传给“润色语音转写”。polished=false 时使用完整原文。
  4. 确认输入框版本和当前会话仍与录音开始时一致,再插入 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用户归属。批量清理某计划产生的会话,使用计划任务下的“删除计划会话分组”;它不暂停或删除计划。