> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aitoearn.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 发起对话

> 使用 `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`。



## OpenAPI

````yaml /openapi/zh/aitoearn.openapi.json post /api/agent/chat
openapi: 3.0.1
info:
  title: AiToEarn 开放平台 API
  description: AiToEarn 开放平台 API，支持在中国站与国际站之间切换调试。业务是否成功以响应体 code === 0 为准。
  version: 1.0.0
  contact: {}
servers:
  - url: https://aitoearn.cn
    description: 中国站
  - url: https://aitoearn.ai
    description: 国际站
security: []
tags:
  - name: AI 服务
  - name: AI 服务/视频生成
  - name: AI 服务/图像生成
  - name: 渠道管理
  - name: 渠道管理/账号
  - name: 渠道管理/内容发布
  - name: 渠道管理/平台
  - name: 渠道管理/作品
  - name: 渠道管理/账号分组
  - name: 渠道管理/授权
  - name: 资源管理
  - name: AI 服务/大语言模型
  - name: AI 服务/真人素材
  - name: AI 服务/Agent
paths:
  /api/agent/chat:
    post:
      tags:
        - AI 服务/Agent
      summary: 发起对话
      description: >-
        使用 `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`。
      operationId: AgentController_chat
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                sessionId:
                  type: string
                  description: 会话 ID。省略时创建新会话。
                messages:
                  type: array
                  description: 本次提交的用户消息或工具审批回执。新会话不能为空。
                  default: []
                  items:
                    type: object
                    properties:
                      role:
                        type: string
                        enum:
                          - user
                          - tool
                        description: 消息角色。user 为用户消息，tool 为工具审批回执。
                      content:
                        description: >-
                          用户消息可以是字符串，或 text/file 分段数组。工具消息必须是
                          tool-approval-response 数组。
                    required:
                      - role
                      - content
                    additionalProperties: true
                model:
                  type: string
                  default: auto
                  description: 模型。传 auto 或具体模型 ID，默认 auto。
                effort:
                  type: string
                  enum:
                    - none
                    - low
                    - medium
                    - high
                    - xhigh
                    - max
                  description: 推理强度。模型不支持该强度时会失败。
                timezone:
                  type: string
                  description: 用户 IANA 时区，例如 Asia/Shanghai。
              additionalProperties: false
            examples:
              default:
                summary: 请求示例
                value:
                  messages:
                    - role: user
                      content: Write a short weekend cafe post.
                  model: auto
      responses:
        '200':
          description: 第三方协议原生响应或 SSE 数据。不使用 AiToEarn 通用响应包裹。
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                description: 第三方协议原生响应，不使用 AiToEarn 通用响应包裹。
              examples:
                success:
                  summary: 第三方协议原生成功响应
                  value:
                    id: AgentController_chat_example
                    object: response
            text/event-stream:
              schema:
                type: string
                description: SSE 流式响应。
      security:
        - apikey-header-X-Api-Key: []
components:
  securitySchemes:
    apikey-header-X-Api-Key:
      type: apiKey
      in: header
      name: X-Api-Key
      description: 需要从 AiToEarn 获取 API Key。点击前往[「API Key 获取教程」](/zh/use/api-key)。

````