---
title: "发起对话"
method: POST
path: "/api/ai/agent/chat"
tags: ["AI 服务/Agent"]
---

# 发起对话

`POST /api/ai/agent/chat`

## Request

- Base URL: `https://aitoearn.cn`
- URL: `https://aitoearn.cn/api/ai/agent/chat`
- Auth: API key in header `X-Api-Key`
- TypeScript: <https://skmtc.dev/aitoearn/apis/aitoearn-api/docs/api/ai/agent/chat/post.ts> (a function with typed inputs; its response is checked against the schema)

使用 `X-Api-Key` 发起或继续 Agent 对话。本接口不接受 `Authorization: Bearer <API Key>`。

省略 `sessionId` 时创建新会话，此时 `messages` 必须包含一条 `role=user` 的消息。继续已有会话、提交工具审批或等待续跑时必须传入 `sessionId`。运行中的会话返回业务码 `18120`，请改用断点续播接口。

成功响应是 AI SDK UI Message SSE 流，不使用 `{ code, data }` 包裹。新会话标题生成后，流内会写入 `data-title`。需要人工审批时，流内会写入 `data-approval-cost`。

## Request body

- object
  - `sessionId` string: 会话 ID。省略时创建新会话。
  - `messages` object[]: 本次提交的用户消息或工具审批回执。新会话不能为空。
    - `role` 'user' | 'tool', required: 消息角色。user 为用户消息，tool 为工具审批回执。
    - `content` unknown, required
  - `model` string: 模型。传 auto 或具体模型 ID，默认 auto。
  - `effort` 'none' | 'low' | 'medium' | 'high' | 'xhigh' | 'max': 推理强度。模型不支持该强度时会失败。
  - `timezone` string: 用户 IANA 时区，例如 Asia/Shanghai。

## Response `200`

第三方协议原生响应或 SSE 数据。不使用 AiToEarn 通用响应包裹。

- object: 第三方协议原生响应，不使用 AiToEarn 通用响应包裹。

## Changes

- **2026-11-03** `7cc8f21c4c96`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/aitoearn/apis/aitoearn-api/changes/api/ai/agent/chat/post.md)

---

[API](https://skmtc.dev/aitoearn/apis/aitoearn-api.md) - [All operations](https://skmtc.dev/aitoearn/apis/aitoearn-api/llms.txt) - [OpenAPI document](https://skmtc.dev/aitoearn/apis/aitoearn-api/revisions/7cc8f21c4c96?raw)