图片与文件附件接入
约 948 字大约 3 分钟
2026-10-16
适用于已协商image/file输入的串联AI会话。先完成快速接入的能力与建会话，但将所需输入模态同时加入能力和创建请求；平台仍需实际模型和原件适配器支持。原生Realtime当前不接这些离散输入。
鉴权与传输
HTTPS设备附件接口使用Authorization: Basic base64(mqttUsername:mqttPassword)，复用当前正式设备认证用户名和签名密码，不发送设备原始secret。完整用户名格式与签名见MQTT认证。Basic头只放HTTP头，不塞JSON；认证通过后还须通过当前设备归属、连接和AI会话授权。
元数据正文为UTF-8 JSON，最多8192字节，拒绝重复键、未知字段及显式null。内容字节只传限时签名PUT，不传MQTT、不用multipart替代原件、不把签名URL当contentRef。
Prepare → PUT → Complete → 输入
准备
POST /api/v1/things/device/edge/content/prepare，Content-Type: application/json：
{"sessionId":"session-demo","requestId":"upload-1","name":"notes.txt","mimeType":"text/plain","size":12,"sha256":"0000000000000000000000000000000000000000000000000000000000000000"}示例size和sha256仅表示字段形状，发送时必须替换为同一实际文件的字节数和64位十六进制SHA256，不允许用全零摘要上传。请求字段全部必填；size为正安全整数。文件类型、大小及过期限制以部署实际策略为准，不假定任意MIME均可读取。
成功响应沿平台HTTP封装，data包含：
| 字段 | 类型 | 设备如何使用 |
|---|---|---|
| contentRef | string | 保存本会话引用，不自行生成 |
| type | string | image或file，后续输入使用同值 |
| mimeType | string | 后续输入沿用实际类型 |
| status | string | uploading或ready |
| uploadUrl | string | uploading时为限时签名PUT；ready重放时为空 |
| uploadReceipt | string | 不透明完成收据，原样保存，不解析或改写 |
| expiresAt | int64 | Unix毫秒截止；ready重放可为0 |
直传与完成
status=uploading时，向返回的uploadUrl执行HTTPS PUT，正文严格为参与摘要计算的原始字节，Content-Type匹配mimeType；不要追加JSON、鉴权头或改变签名URL。仅按签名服务要求附加头，不泄漏平台Basic凭据到对象存储。PUT失败不能提交为成功。
PUT成功后，POST /api/v1/things/device/edge/content/complete，沿用设备Basic认证：
{"sessionId":"session-demo","contentRef":"authorized-file-ref","uploadReceipt":"opaque-receipt-returned-by-prepare"}以上三个字段全部必填，值取实际Prepare。成功data含contentRef/type/mimeType/status，status为ready。若Prepare幂等重放已经ready，可直接使用其就绪引用，不对空URL执行PUT。
引用提交
按真实完成结果替换下面引用，发上行message：
{"msgToken":"input-file-1","method":"inputSend","sessionId":"session-demo","params":{"inputId":"file-input-1","contents":[{"type":"text","text":"请概括附件内容。"},{"type":"file","contentRef":"authorized-file-ref","mimeType":"text/plain"}],"outputModalities":["text"]}}图片使用type=image及实际image MIME；不要改为imageUrl。确认ACK后按原inputId／respId等候内容及respDone，完整事件见快速接入。Complete只说明原件ready，ACK只说明队列受理，两者均不证明模型已理解附件。
失败与撤权
同requestId必须保持相同元数据，不换ID重复写。MIME、字节数、摘要不符必须拒绝；重新连接、设备转移、会话结束、引用过期或撤权后不能消费原引用。不能借用通用上传、工作台上传或另一会话的URL绕过范围。
附件解析在原回复worker中执行，不阻塞信令收发；受理后的解析失败、撤权或取消通过原respDone结束，不补发第二份拒绝ACK。不假定已签发PUT链接能即时撤销，更不能承诺抹除模型之前已接收的内容。
更新日志
2026/10/16 16:04
查看所有更新日志
fe3a7-docs(AI与音视频): 按场景整理完整接入流程与命令契约于