Messages 对话

使用 Messages 协议发起普通文本、附件、会话续接、后台任务和 SSE 对话。

端点：POST /openapi/v1/messages

Messages 是 Poco 对外集成的完整对话协议，支持普通文本、图片、文件、会话续接、幂等请求、后台执行、SSE 和 JSON Schema 结构化输出。

请求头

x-api-key: sk-xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

请求参数

参数	类型	必填	说明
`model`	string	是	协议兼容和响应回显字段；实际模型由 API Key 配置决定
`messages`	array	是	至少一条消息；当前使用最后一条 `user` 消息
`stream`	boolean	否	默认 `false`；`true` 返回 SSE
`background`	boolean	否	默认 `false`；`true` 时以后台任务提交并立即返回
`background_payload`	Base64 string	否	后台任务的业务透传数据，最长 8192 个字符
`metadata.session_id`	UUID string	否	续聊当前用户有权访问且绑定 Key 匹配的会话
`idempotency_key`	string	后台任务必填	业务请求标识，最长 128 个字符
`output_format`	object	否	需要结构化输出时传入 JSON Schema
`system`	string / array	否	协议兼容字段；当前执行链路不把它作为 Agent 输入
`max_tokens`	integer	否	协议兼容字段；当前不会覆盖 Agent 运行配置
`temperature`、`top_p`、`top_k`	number	否	协议兼容字段；当前不会覆盖 Agent 运行配置
`stop_sequences`	string[]	否	协议兼容字段；当前不会覆盖 Agent 运行配置

普通首次请求按用户、Key、执行目标和创建幂等键复用已有会话与运行；续聊在同一会话内重复使用相同 idempotency_key 返回已有运行。后台请求在同一 API Key 下全局幂等，即使首次提交时没有传 metadata.session_id，重试也会返回原来的会话和运行。接口不会比较两次请求体是否一致，只有重试同一次业务请求时才能复用该值。

请求模型允许额外字段，以便兼容现有客户端，但未在本文明确说明的字段不保证具备对应执行语义。

非流式文本对话

curl -X POST 'https://<poco-host>/openapi/v1/messages' \
  -H 'x-api-key: sk-xxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "poco-agent",
    "stream": false,
    "messages": [
      {"role": "user", "content": "你好"}
    ]
  }'

{
  "id": "msg_123456",
  "type": "message",
  "role": "assistant",
  "content": [{ "type": "text", "text": "你好，我可以帮你处理这个请求。" }],
  "model": "poco-agent",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 123,
    "output_tokens": 456,
    "cache_creation_input_tokens": null,
    "cache_read_input_tokens": null
  },
  "structured_output": null
}

响应头：

X-Session-Id：本次会话 ID，用于继续会话或查询完整产物。
X-Run-Id：本轮运行 ID，用于查询本轮新增或修改的产物。

后台执行

耗时任务可以在原 Messages 请求中设置 background=true。后台执行必须同时满足：

stream=false。
提供非空 idempotency_key。
background_payload 如存在，必须是标准 Base64 字符串。

background_payload 只负责原样保存和返回，是编码而不是加密。调用方如需传递敏感业务数据，应先自行加密，再把密文编码为 Base64。

curl -X POST 'https://<poco-host>/openapi/v1/messages' \
  -H 'x-api-key: sk-xxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "poco-agent",
    "stream": false,
    "background": true,
    "idempotency_key": "order-BIZ20260001-v1",
    "background_payload": "eyJvcmRlcl9pZCI6IkJJWjIwMjYwMDAxIn0=",
    "messages": [
      {"role": "user", "content": "分析仓库并输出改进建议"}
    ]
  }'

提交成功返回 HTTP 202，响应仍采用标准非流式 Message 结构。首次提交尚未生成结果时使用空内容、空终止原因和零用量；幂等重放返回原 Run 当前状态，已完成时可带最终内容和结构化结果。新增的 background_results 提供查询信息：

{
  "id": "msg_<stable-run-message-id>",
  "type": "message",
  "role": "assistant",
  "content": [],
  "model": "poco-agent",
  "stop_reason": null,
  "stop_sequence": null,
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "cache_creation_input_tokens": null,
    "cache_read_input_tokens": null
  },
  "structured_output": null,
  "background_results": {
    "session_id": "<session-uuid>",
    "run_id": "<run-uuid>",
    "status": "queued",
    "result_url": "/openapi/v1/runs/<run-uuid>",
    "retry_after_ms": 2000,
    "background_payload": "eyJvcmRlcl9pZCI6IkJJWjIwMjYwMDAxIn0=",
    "error": null
  }
}

响应头继续包含 X-Session-Id 和 X-Run-Id，等待中的响应同时包含 Retry-After: 2。按 result_url 查询最终结果，具体状态和响应见会话管理中的后台结果查询。

后台任务执行遵守以下隔离和并发规则：

提交后台任务时，目标会话不能已有未完成运行；提交成功后，同一会话的后续普通请求仍按现有会话队列规则处理。
默认每个 API Key 最多 20 个未完成后台任务、其中最多 2 个同时执行；同一用户全部 Key 默认最多 50 个未完成任务。
全局队列上限为可用 OpenAPI Worker 容量的 10 倍；注册表从未存在 Worker 时使用固定容量 5。已有注册记录时按在线且支持 openapi 调度的节点计算，无可用容量或队列满返回 HTTP 503。
排队超过默认 3600 秒的任务返回 failed 和 queue_timeout_error。
上述限制只作用于 background=true 的 OpenAPI 任务，不改变普通非流式、流式或主对话链路。

执行目标可为自由模式、单个专家或专家团，见 API Key 管理。团队新会话保存当时的编排，续聊使用该会话快照。任何读取或续聊都检查用户和绑定 Key；不能用同一账号另一把 Key 交叉访问。

继续已有会话

{
  "model": "poco-agent",
  "stream": false,
  "messages": [{ "role": "user", "content": "继续这个会话" }],
  "metadata": {
    "session_id": "<existing-session-uuid>"
  }
}

每一轮只需要提交新的用户输入，不需要把完整历史消息重新发送给 Poco。

图片和文件

{
  "model": "poco-agent",
  "stream": false,
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "请总结文档并结合图片给出结论" },
        {
          "type": "image",
          "file_name": "screen.png",
          "source": {
            "type": "base64",
            "media_type": "image/png",
            "data": "<BASE64_IMAGE>"
          }
        },
        {
          "type": "file",
          "file_name": "spec.pdf",
          "source": {
            "type": "base64",
            "media_type": "application/pdf",
            "data": "<BASE64_PDF>"
          }
        }
      ]
    }
  ]
}

支持的来源：

内容块	支持来源
`image`	`base64`、HTTP(S) URL、Data URL、`attachments/...`
`file` / `document`	`base64`、Data URL、`attachments/...`

图片的 HTTP(S) URL 在受理请求时由 Backend 下载并保存为附件，下载超时为 60 秒，大小上限与附件上传一致（MAX_UPLOAD_SIZE_MB）。地址无法访问、返回非 2xx 或返回的不是 image/* 时返回 HTTP 400，超过大小上限返回 HTTP 413，均不会创建运行。URL 必须能从 Backend 访问。

file 和 document 当前不支持 HTTP(S) 直链下载。大文件还可能受到入口网关和服务端请求体大小限制。

流式响应

stream=true 时返回 text/event-stream。常见事件包括：

message_start
content_block_start
content_block_delta
content_block_stop
message_delta
message_stop
result（结构化输出成功时）
error
ping

event: message_start
data: {"type":"message_start","message":{"id":"msg_xxx","role":"assistant","content":[]}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"你好"}}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"output_tokens":12}}

event: message_stop
data: {"type":"message_stop"}

普通文本消费者应按 index 拼接内容块，并在 message_stop 后结束。收到 error 时本轮失败，不应继续等待正常结束事件。

需要直接得到可校验的 JSON 时，继续阅读结构化输出。