Jenova 智能体 API 参考

基础 URL： https://api.jenova.ai/v1

身份验证： 在 Authorization 标头中携带 Bearer token

目录

• 概述
• 快速入门
• 核心概念
• 身份验证
• API 端点
  • 消息 API
  • 会话 API
  • 操作
  • 额度
  • 智能体 API
  • 模型
  • 文档
• 流式传输（SSE）
• MCP 服务器集成
• 账单
• 速率限制
• 错误处理
• 分页
• 本地化
• 隐私与数据
• 支持

概述

几分钟即可在你的产品或工作流中运行自定义智能体。为任意任务配置好智能体，任选模型与工具，智能体 Harness、数据库与扩容交给 Jenova。

完整的智能体技术栈：

• 托管智能体 Harness： 一次调用，产出成品。你的智能体研究、推理、调用工具并生成文件——严格按你的指令执行。
• 无上限的上下文与记忆： RAG 驱动的上下文管理与专有的会话状态跟踪，共同实现会话内的无限记忆。
• 工具与 MCP 资源库： 连接我们资源库中的 30+ 工具与 MCP 服务器，例如搜索、图像生成、邮件等——或接入你自己的 MCP 服务器。
• 任意模型，无缝切换： 部署来自 OpenAI、Anthropic、Google、xAI 或领先开源厂商的模型，只需一个参数即可在模型之间切换。
• 托管知识与 RAG： Jenova 负责端到端 RAG 管线——分块、索引、存储与检索。
• 历经大规模验证： 在久经考验的基础设施上部署——生产环境中已有数百个智能体运行其上。无需预置、扩容或维护任何集群。

快速入门

1. 获取您的 API 密钥

请在开发者控制面板 www.jenova.ai/platform 中生成 API 密钥。密钥格式为 jnv_sk_*，以 Bearer token 形式传递。

2. 选择或创建智能体

您可以从平台中选择预构建的智能体，也可以在控制面板中创建自定义智能体，并配置指令、模型设置、知识库文件、工具以及 MCP 服务器。

3. 发送您的第一条消息

通过一次调用即可创建会话并发送消息：

curl -N -X POST https://api.jenova.ai/v1/messages \
  -H "Authorization: Bearer jnv_sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "content": "What can you help me with?"
  }'

响应以 Server-Sent Events 的形式流式返回：

event: stream_started
data: {"session_id":"ses_xyz789","run_id":"run_abc123","agent":"my-support-agent"}

event: stream_delta
data: {"session_id":"ses_xyz789","run_id":"run_abc123","chunk_content":"I can help you with ","seq":1}

event: stream_ended
data: {"session_id":"ses_xyz789","run_id":"run_abc123","success":true,"stop_reason":"end_run","usage":{"cost":"0.0032"}}

请从 stream_started 事件中获取 session_id，以便用于后续请求。若需了解同步 JSON 响应方式，请参阅发送消息。

核心概念

智能体

您通过 API 交互的 AI 智能体。每个智能体都有一个唯一的 slug（例如 my-support-agent），在 API 调用中作为 agent 值使用。

• 预构建： 从平台上已有的智能体中进行选择。
• 自定义： 在控制面板中配置您自己的智能体，包括指令、模型、知识库、工具和 MCP 服务器。

会话

终端用户与智能体之间的一段独立对话线程。

• 标识符： 带前缀的 ID（例如 ses_abc123）。
• 范围： 同一个智能体与同一终端用户之间可以存在多个会话，每个会话都拥有独立的对话状态。
• 生命周期： 会话会一直保留，直到通过 API 删除为止。对于不需要会话的一次性任务，请使用 POST /messages 并设置 ephemeral: true。
• 平台隔离： API 会话与 Jenova 网页应用中的对话是相互独立的。终端用户、会话历史记录以及账单在 API 与网页应用之间彼此独立。

消息

会话对话历史中的单条记录，由消息 API相关端点返回。每条消息都包含一个结构化的 from 对象，其中含有 type（user 或 agent）和 name，此外还有消息本身的 type：

• external —— 用作聊天内容展示的对话消息。
• internal —— 一种可选消息，用于表示运行期间智能体的工作步骤，例如工具调用或检索。

运行

发送消息时创建的一次智能体执行。每次运行都有一个 run_id，在活动期间可能会流式传输事件，并可能会生成一条或多条已完成的消息。每个会话在任意时刻只能有一个活动运行。

终端用户

user 字段用于将会话限定到您应用中的某个终端用户。请使用稳定的不透明 ID，例如您内部的用户 ID 或 UUID。除非您的应用确有需要，请避免使用电子邮件或其他个人身份信息（PII）。使用相同 user 值创建的会话会被归为一组，从而支持按终端用户列出会话。

如果省略 user，则该会话将归属于您的开发者账户，此后无法按终端用户进行筛选。在生产环境中请务必传入 user。

对于针对已有会话的请求（即路径中包含 {session_id} 的任何端点），user 是一个可选的所有权校验字段。如果您提供了该字段，其值必须与创建会话时所使用的 user 值一致；否则 API 将返回 404 session_not_owned。请在 GET 和 DELETE 请求中以查询参数形式传递该字段，在 POST 和 PATCH 请求中则以 JSON 正文形式传递。在 POST 或 PATCH 请求中以查询参数形式传递 user 将返回 400 bad_request。

身份验证

对每个请求都必须使用 Authorization 标头中的 Bearer token 进行身份验证：

Authorization: Bearer jnv_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API 密钥从开发者控制面板生成。

User-Agent 是可选的。SDK 可以为诊断目的设置该标头，但 API 并不要求提供它。

密钥格式： 密钥以前缀 jnv_sk_ 开头，后跟一个 base62 编码的随机字符串。

限制： 每个开发者账户最多可以拥有 10 个有效 API 密钥。

API 端点

消息 API

发送消息是主要的 API 路径。首次发送消息时使用 POST /messages；该请求会在一次调用中创建会话并启动运行。当需要继续使用已获取的 session_id 时，则使用 POST /sessions/{session_id}/messages。

发送消息

POST /messages

在一次请求中创建持久化会话并发送首条消息。设置 ephemeral: true 可发起一次流式单次请求，该请求不返回会话 ID，且无法继续。其数据会在请求完成后不久被删除。

请求正文

示例 - 流式传输（默认）

curl -N -X POST https://api.jenova.ai/v1/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "content": "Hello, I need help with my account"
  }'

响应是一个 SSE 流（有关事件格式，请参阅流式传输（SSE））。持久化请求会包含新的 session_id；ephemeral: true 的请求不包含 session_id，且必须使用流式传输。

示例 - JSON（非流式传输）

curl -X POST https://api.jenova.ai/v1/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "content": "Hello, I need help with my account",
    "stream": false
  }'

响应

流式传输响应会发出流式传输（SSE）中记录的 SSE 事件。非流式传输响应返回消息对象，其中包含该请求的 stop_reason 和 usage，如继续会话所示。stop_reason 为 end_run；如果运行在智能体生成消息之后被取消，则为 user_cancelled。

如果运行在智能体生成消息之前被取消，API 将返回 200 OK，其中包含 status: "cancelled"、session_id、run_id、stop_reason: "user_cancelled" 和 usage。

如果一次非流式传输运行在 90 秒后仍在处理中，API 会返回 202 Accepted，并附带 status: "processing"、session_id、run_id 和一条人类可读的 message。该运行会在响应返回或客户端断开连接后继续执行；您可以检查该会话的消息，或对较长的工作流使用流式传输。

错误

继续会话

POST /sessions/{session_id}/messages

向现有的持久化会话发送消息，并接收智能体的响应。默认情况下，响应通过 SSE 流式传输；如需 JSON，请设置 stream: false。

请求正文

示例 - 流式传输（默认）

curl -N -X POST https://api.jenova.ai/v1/sessions/ses_abc123/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "How do I reset my password?"
  }'

示例 - JSON（非流式传输）

curl -X POST https://api.jenova.ai/v1/sessions/ses_abc123/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "How do I reset my password?",
    "stream": false
  }'

响应 200 OK

{
  "id": "msg_xyz789",
  "session_id": "ses_abc123",
  "sequence": 4,
  "from": {
    "type": "agent",
    "name": "my-support-agent"
  },
  "type": "external",
  "time": "2026-05-19T10:31:05Z",
  "content": "To reset your password, go to Settings > Security > Change Password...",
  "model": "claude-sonnet-5",
  "files": [],
  "stop_reason": "end_run",
  "usage": {
    "cost": "0.0015"
  }
}

如果该会话已存在活跃的运行或已排队的消息，API 将返回 JSON 202 Accepted，其中包含 status: "queued"、session_id、run_id 和 message_id。该用户消息将由活跃的运行处理。包含 additional_context 的请求则会返回 409 busy。

非流式传输响应遵循与发送消息相同的规则，包括在智能体生成消息之前运行被取消时返回的 status: "cancelled" 响应。

错误

幂等性

POST /messages、POST /sessions/{session_id}/messages 和 POST /invoke 接受一个可选的 Idempotency-Key 标头（最多 255 个字符）。请为每次用户逻辑发送使用唯一的键，以避免网络重试或重复提交导致创建重复的运行。键会保留 24 小时。

curl -N -X POST https://api.jenova.ai/v1/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: send-user_12345-2026-05-19T10:30:00Z" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "content": "Hello"
  }'

非流式： 重试将返回已保存的响应，并附带 Idempotent-Replayed: true 标头，其中包括请求开始处理后返回的错误。已保存的 202 Accepted 响应会原样重放；请使用获取运行状态或列出消息检查结果。在开始处理之前即被拒绝的请求（例如校验错误或额度错误）不会被保存，因此重试时会重新进行评估。

流式传输： 该流不会被重放。对于 POST /messages 和 POST /sessions/{session_id}/messages，在运行期间或完成之后重试，都会返回一个幂等性错误，其中包含原始的 run_id，对于持久化请求还会包含 session_id。对于持久化请求，可使用获取运行状态检查活动中的运行，或使用列出消息获取已持久化的结果。流式 POST /invoke 的结果在流关闭后无法获取。 POST /invoke 重试返回原始的 id，而不是 run_id 和 session_id。

已完成的流式重试示例：

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error": {
    "code": "idempotency_key_reused",
    "message": "This Idempotency-Key has already completed. Streaming responses cannot be replayed; use the returned session_id and run_id to retrieve the result."
  },
  "idempotency": {
    "status": "completed",
    "session_id": "ses_abc123",
    "run_id": "run_abc123"
  }
}

幂等性错误

列出消息

GET /sessions/{session_id}/messages

返回该会话消息的分页列表。默认情况下仅返回 external 对话消息。第一页包含最新的消息；在每一页内，消息按时间顺序排列（最早的在前）。sequence 是该消息在会话内的排序编号。

查询参数

示例

curl "https://api.jenova.ai/v1/sessions/ses_abc123/messages?limit=50" \
  -H "Authorization: Bearer jnv_sk_xxx"

响应 200 OK

{
  "items": [
    {
      "id": "msg_002",
      "session_id": "ses_abc123",
      "sequence": 4,
      "from": {
        "type": "agent",
        "name": "my-support-agent"
      },
      "type": "external",
      "time": "2026-05-19T10:31:05Z",
      "content": "To reset your password, go to Settings > Security...",
      "model": "claude-sonnet-5",
      "stop_reason": "end_run"
    }
  ],
  "next_cursor": "",
  "has_more": false
}

Message 对象

File 对象

错误

获取消息

GET /sessions/{session_id}/messages/{message_id}

按 ID 检索单条消息。

查询参数

响应 200 OK

返回单个消息对象，结构与列表响应相同。

错误

文件附件

在 file_urls 字段中传入可公开访问的 HTTPS URL。

支持的格式

• 图片： JPG、JPEG、PNG、WebP
• 文档： PDF、DOCX、XLSX、PPTX、TXT、CSV、RTF、MD、HTML、XML、JSON、LOG
• 代码： JS、TS、TSX、JSX、PY、Java、Go、C、CPP、H、HPP、CS、RB、PHP、RS、Swift、KT、Scala、SQL、CSS、YAML、YML

文件 URL 会在智能体于运行期间读取它们时才被获取，而不是在请求被接受时获取。无法获取的 URL 或超过 20 MB 的文件不会被读取；请求本身不会因此被拒绝。

在列出消息时，附加的文件会出现在消息的 files 数组中。

附加上下文

在 additional_context 中为单条消息传入命名上下文，例如终端用户的账户信息。它不会保存到消息历史中。

请使用描述性名称，例如 customer_profile 或 order_details。

如果某个条目缺少 name 或 content，或其值不是字符串，将返回 400 invalid_payload。其他无效条目返回 400 bad_request。

curl -N -X POST https://api.jenova.ai/v1/sessions/ses_abc123/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "How do I reset my password?",
    "additional_context": [
      {
        "name": "customer_profile",
        "content": "Plan: Pro. Last login: 2026-05-18."
      }
    ]
  }'

会话 API

会话是终端用户与智能体之间的持久对话。大多数集成可以通过 POST /messages 隐式创建会话。

创建会话

POST /sessions

创建绑定到特定智能体的空持久会话。当您需要在发送第一条消息之前获取会话 ID 时使用此端点；否则请优先使用 POST /messages。

说明： POST /sessions 不接受 ephemeral 参数；如需一次性请求，请对 POST /messages 使用 ephemeral: true。

请求正文

示例

curl -X POST https://api.jenova.ai/v1/sessions \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "session_name": "Billing inquiry"
  }'

响应 201 Created

{
  "id": "ses_abc123",
  "session_name": "Billing inquiry",
  "agent": "my-support-agent",
  "user": "user_12345",
  "model": "claude-sonnet-5",
  "created_at": "2026-05-19T10:30:00Z",
  "updated_at": "2026-05-19T10:30:00Z"
}

Session 对象

错误

列出会话

GET /sessions

返回您的会话的分页列表，按最近更新时间排序。

查询参数

示例

curl "https://api.jenova.ai/v1/sessions?user=user_12345&limit=10" \
  -H "Authorization: Bearer jnv_sk_xxx"

响应 200 OK

{
  "items": [
    {
      "id": "ses_abc123",
      "session_name": "Billing inquiry",
      "agent": "my-support-agent",
      "user": "user_12345",
      "model": "claude-sonnet-5",
      "created_at": "2026-05-19T10:30:00Z",
      "updated_at": "2026-05-19T11:15:00Z"
    }
  ],
  "next_cursor": "2026-05-19T11:15:00Z|ses_abc123",
  "has_more": true
}

错误

获取会话

GET /sessions/{session_id}

按 ID 检索单个会话。

查询参数

响应 200 OK

返回一个会话对象。

错误

重命名会话

PATCH /sessions/{session_id}

更新会话的显示名称。

请求正文

响应 200 OK

返回更新后的会话对象。

错误

删除会话

DELETE /sessions/{session_id}

永久删除会话及其所有消息。该会话不能存在活动运行。

响应 204 No Content

错误

操作

这些端点是用于持久会话的恢复与编辑控制。大多数集成场景只需要使用取消活动运行；仅在您有意要更改或恢复会话状态时，才使用其他操作。所有操作均支持终端用户中描述的可选 user 所有权保护机制。

取消活动运行

POST /sessions/{session_id}/cancel

取消活动中的智能体运行。此操作不会删除取消之前已完成的消息。

请求正文

响应 204 No Content

错误

撤销活动运行

POST /sessions/{session_id}/undo

取消活动运行，等待其停止，然后移除其已添加的所有消息。发出撤销请求后不会再持久化任何额外输出。

请求正文

响应 200 OK

{
  "session_id": "ses_abc123",
  "run_id": "run_abc123",
  "deleted": ["msg_002", "msg_001"]
}

如果在任何消息完成之前该运行就被取消，deleted 将是一个空数组。

错误

删除最近的消息

POST /sessions/{session_id}/messages/delete

从空闲会话中删除最近的 count 条消息，包括 internal 消息。可在列出消息中使用 include=all 查看这些消息。该会话必须没有正在进行的运行。

请求正文

响应 200 OK

{
  "deleted": ["msg_002", "msg_001"]
}

错误

分叉会话

POST /sessions/{session_id}/fork

通过复制源会话中截至特定消息的内容来创建新会话。源会话必须没有正在进行的运行。

请求正文（可选）

响应 201 Created

返回新创建的会话对象，其结构与创建会话时相同。

错误

获取运行状态

GET /sessions/{session_id}/runs/{run_id}

返回正在进行的运行的当前状态。在 SSE 连接中断或幂等性响应返回了 run_id 之后，可使用此接口。运行结束后，请通过 GET /sessions/{session_id}/messages 获取结果。

响应 200 OK

{
  "session_id": "ses_abc123",
  "run_id": "run_abc123",
  "status": "streaming",
  "started_at": "2026-05-19T10:30:00Z",
  "updated_at": "2026-05-19T10:30:06Z",
  "content": "Partial visible response text so far"
}

status 在智能体工作期间为 running，开始生成响应文本后为 streaming，运行结束后的短时间内为 ended。响应中还可能包含记录最近活动的 progress_events，其格式与 stream_progress 相同。当 status 为 ended 或请求返回 404 not_found 时，请获取该会话的消息。

错误

额度

获取余额

GET /credits/balance

返回您当前的额度余额。

响应 200 OK

{
  "balance": "123.45"
}

智能体 API

在控制面板中创建和编辑自定义智能体。通过 API 创建和编辑智能体的支持即将推出。

目前尚不支持通过 API 使用计划/后台工作流。相关支持即将推出。

列出智能体

GET /agents

返回您的账户可用的智能体。创建会话或发送消息时，请使用 agent 值。

响应 200 OK

{
  "agents": [
    {
      "agent": "jenova",
      "display_name": "Jenova",
      "description": "General-purpose Jenova agent"
    },
    {
      "agent": "my-support-agent",
      "display_name": "Support Agent",
      "description": "Answers customer questions"
    }
  ]
}

模型

列出模型

GET /models

返回发送消息或调用 POST /invoke 时可用于 model 字段的所有模型。

响应 200 OK

{
  "models": [
    {
      "id": "claude-opus-4-8",
      "name": "Claude Opus 4.8",
      "thinking_variant": "claude-opus-4-8-thinking"
    },
    {
      "id": "claude-opus-4-8-thinking",
      "name": "Claude Opus 4.8 (Thinking)"
    },
    {
      "id": "claude-sonnet-5",
      "name": "Claude Sonnet 5",
      "thinking_variant": "claude-sonnet-5-thinking"
    }
  ]
}

带有 thinking_variant 的模型支持扩展推理。要启用它，请直接在 model 字段中使用该变体 ID。

如果发送消息时未指定 model，则使用会话的 model。该值在创建会话时设为智能体的默认模型。

调用模型

POST /invoke

直接向模型发送提示词，不经过智能体、会话或工具。默认情况下，响应通过 SSE 流式传输；如需 JSON，请设置 stream: false。

请求正文

示例

curl -X POST https://api.jenova.ai/v1/invoke \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "content": "Describe a forest in one sentence.",
    "stream": false
  }'

响应 200 OK

{
  "id": "inv_abc123",
  "model": "claude-sonnet-5",
  "content": "Sunlight filters through tall pines onto a quiet, mossy floor.",
  "usage": {
    "cost": "0.0004"
  }
}

流式传输响应先发送 stream_started，随后在模型生成文本时发送 stream_delta 事件，最后以包含 usage 的 stream_ended 结束。按 seq 顺序拼接 chunk_content 值即可构建流式传输的响应。如果请求失败，会在 stream_ended 之前发送 stream_error。事件携带 id，而不是 session_id 和 run_id。

usage.cost 在费用不可用时为 null。如果非流式请求在模型调用开始后失败，错误响应将包含顶层的 id 和 usage 字段。

流式请求时长上限为 120 分钟。非流式请求最长等待 30 分钟获取结果，而不是返回 202 Accepted；如果届时结果仍未就绪，将返回错误。

错误

文档

GET /docs?lang=en
GET /doc?lang=en

以 Markdown 格式返回本参考文档。使用 lang 选择语言。

流式传输（SSE）

当省略 stream 或将其设为 true（默认值）时，消息响应将以 Server-Sent Events 形式传递。使用 message_completed 事件来识别已准备好可获取或渲染的消息。

超时： SSE 连接会一直保持打开状态，直到运行结束。运行时长上限为 120 分钟。非流式消息请求最长等待 90 秒，随后在运行仍在继续时返回 202 Accepted。非流式 POST /invoke 请参阅调用模型。

连接标头

消息流会设置以下标头：

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
X-Accel-Buffering: no
X-Run-Id: run_abc123

X-Run-Id 在第一个 SSE 事件之前即可获取。POST /invoke 流不会设置 X-Run-Id；请使用 stream_started 中的 id。

重新连接与恢复

SSE 流不会被重放。如果持久化请求的连接中断，请使用已捕获的 session_id 和 run_id 来恢复状态：

curl "https://api.jenova.ai/v1/sessions/ses_abc123/runs/run_abc123" \
  -H "Authorization: Bearer jnv_sk_xxx"

如果该运行仍处于活动状态，此请求将返回当前状态、部分文本以及最近的进度。如果返回 status: "ended" 或 404 not_found，说明该运行已不再活动；请获取该会话的消息以核对已完成的输出：

curl "https://api.jenova.ai/v1/sessions/ses_abc123/messages?limit=20" \
  -H "Authorization: Bearer jnv_sk_xxx"

帧格式

每个 SSE 帧遵循标准格式：

event: <event_type>
data: <json_payload>

两个换行符用于结束每个帧。

事件类型

流包含生命周期、文本增量、思考、进度、警告、消息完成、MCP 连接、错误、最终以及 ping 事件。某些事件类型仅在相关时才会发送。

对于临时请求（ephemeral: true），每个 SSE 事件都会省略 session_id。请仅使用 run_id 来关联该单次流内的事件。

对于持久性请求的最终核对，请等待 stream_ended，然后调用列出消息。

运行范围事件的通用字段：

stream_started

运行开始时发送一次。

stream_delta

在智能体生成可见响应文本时反复发送。按 seq 顺序拼接 chunk_content 值即可构建流式传输的响应。

event: stream_delta
data: {"session_id":"ses_abc123","run_id":"run_abc123","chunk_content":"To reset your ","seq":1}

stream_thinking

在智能体输出思考内容时反复发送。请将其用于单独的思考指示器或跟踪视图；不要将其拼接进最终响应文本中。

stream_progress

报告生成过程中用户可见的活动，例如读取文档、搜索网页或等待用户操作。这些事件用于临时性 UI 展示；请忽略未知字段。要获取权威的消息历史，请使用已完成的消息。

在消息请求中设置 include_progress: false 可仅省略 stream_progress。生命周期事件、ping、message_completed、错误以及终止事件在相关时仍会发送。

某些进度事件可能包含 url、file_name 或 server_name 作为可选的展示提示。

message_completed

每当消息完成并可供获取或渲染时发送。

这是一个边界标记，并非完整的消息对象。如需内容或元数据，请获取该消息。

event: message_completed
data: {"session_id":"ses_abc123","run_id":"run_abc123","message_id":"msg_abc123","sequence":4,"from":{"type":"agent","name":"my-support-agent"},"type":"external"}

mcp_connection

当智能体在继续之前需要终端用户连接或授权一个或多个 MCP 服务器时发送。此事件仅在流式传输模式下可用。

mcp_connection_resolved

当 MCP 连接用户操作已解决或已过期时发送。

除通用运行范围字段外，无其他附加字段。

warning

在运行过程中出现非致命警告时发送。

stream_error

运行失败时发送。随后可能会跟随一个 success: false、stop_reason: "error" 的最终 stream_ended 事件。

stream_ended

运行结束时发送一次。这是该流的最后一个事件。

event: stream_ended
data: {"session_id":"ses_abc123","run_id":"run_abc123","success":true,"stop_reason":"end_run","usage":{"cost":"0.0032"}}

已取消运行示例：

event: stream_ended
data: {"session_id":"ses_abc123","run_id":"run_abc123","success":false,"stop_reason":"user_cancelled","usage":{"cost":"0.0012"}}

ping

每 15 秒 发送一次的保活帧，用于防止代理/CDN 超时。您的客户端应忽略这些帧。

MCP 服务器集成

通过 Model Context Protocol (MCP) 将您的智能体连接到外部工具：

• Jenova 托管的 MCP 服务器： 由 Jenova 托管的服务器，提供搜索、内容检索、文档生成等内置能力
• 远程 MCP 服务器： 为您的智能体配置的其他远程 MCP 服务器

MCP 服务器必须在创建或编辑智能体时在控制面板中配置。若要使用您自己的 MCP 服务器，请将其添加到自定义智能体，然后通过 API 调用该智能体。API 会执行在智能体配置中启用的工具；无需在 API 请求中进行额外设置。

当智能体在响应过程中使用 MCP 工具时，进度事件会在事件发生时通过流发送：

event: stream_progress
data: {"session_id":"ses_...","run_id":"run_...","state":"running","label":"Searching Google"}

如果智能体在运行期间需要终端用户连接或授权某个 MCP 服务器，流式响应可能包含 mcp_connection 和 mcp_connection_resolved 事件。请将连接服务器列表展示给您的终端用户，并在提供 auth_url 时打开该链接。在终端用户连接或授权服务器期间，请保持 SSE 流处于打开状态。

授权完成后，Jenova 会存储该 token，授权窗口会显示一个完成页面，同一运行会自动继续。终端用户无需重新发送消息。

如果终端用户在 user_action_deadline_unix 之前未连接、授权，也未跳过或静音，运行将以 stop_reason: "user_action_timeout" 结束。您也可以通过 POST /sessions/{session_id}/cancel 取消当前活动的运行。

请在客户端保存 auth_url。如果客户端在授权期间断开连接，该 URL 在 user_action_deadline_unix 之前仍然有效。对于持久化请求，可通过获取运行状态检查运行，或在运行结束后获取消息。

非流式请求（stream: false）不支持 MCP 连接用户操作；对于可能需要此类交互的智能体，请使用流式传输。

跳过 MCP 连接

POST /sessions/{session_id}/mcp/connection/skip

驳回一个待处理的 MCP 连接用户操作，使运行无需该连接即可继续。

若要为同一终端用户和智能体静音某个服务器未来的连接提示，请包含 mcp_server_id 和 mute。mute 接受时长（例如 30m、24h 或 7d）或 forever。

请求正文

响应 204 No Content

该流会发出 mcp_connection_resolved，随后运行以相同的 run_id 继续。

错误

账单

所有费用均从您的开发者额度余额中扣除。可在 www.jenova.ai/platform 查看用量并充值额度。

定价

消息费用取决于以下因素：

• 模型 - 不同模型的每 token 费用不同
• 上下文长度 - 会话越长，每次请求消耗的输入 token 越多
• 工作流复杂度 - 更长的工作流以及更繁重的工具使用（网络搜索、文件生成、文档分析）会增加总 token 消耗

对于流式请求，实际费用以 stream_ended.usage.cost 返回；对于非流式 JSON 请求，则以 usage.cost 返回。

额度冻结

每个 POST /messages、POST /sessions/{session_id}/messages 和 POST /invoke 请求在开始执行前，都会在您的额度余额上产生 $0.50 的冻结。这是为该请求预留资金。排入活动运行队列的消息（202 Accepted 且 status: "queued"）不会产生额外的冻结；该活动运行的用量会与您的剩余余额进行核对。

请求完成后，冻结金额会结算为实际费用，差额将被释放。如果实际费用超过冻结金额，超出部分也会被扣除，因此您的余额可能变为负数。已取消和失败的请求仅按已产生的用量计费。如果请求在到达模型之前失败，全部冻结金额都会被释放。

由于存在冻结，在请求进行期间，您的可用余额可能会暂时显示较低。对于 POST /sessions/{session_id}/messages、临时 POST /messages 或 POST /invoke 请求，您的可用余额至少需要 $0.50。持久性的 POST /messages 请求还会创建一个会话，因此至少需要 $0.51，以覆盖冻结金额加上创建会话的费用。

速率限制

每个开发者账户均受以下三个速率限制维度的约束：

运行在结束前会一直占用并发名额，即使已返回 202 Accepted 响应或客户端已断开连接。POST /invoke 请求在完成前会一直占用名额，即使客户端已断开连接。

GET 和 HEAD 请求不占用并发名额。cancel、undo 以及 mcp/connection/skip 也不占用并发名额，因此即使所有名额都已被占用，这些操作仍然可用。这些请求仍会计入 RPM 和 RPD。

此外，所有请求还受单独的按 IP 限制（每 60 秒 1,200 个请求），超出时返回相同的 429 rate_limit_exceeded 错误。

响应标头

经过身份验证的 API 响应中包含速率限制标头：

超出每日限制时，X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset 改为描述每日窗口。

超出限制时，API 将返回 429 Too Many Requests：

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please try again later."
  }
}

错误处理

即时 HTTP 错误和非流式运行错误遵循统一的信封格式：

{
  "error": {
    "code": "error_code_string",
    "message": "Human-readable description"
  }
}

错误消息会根据 lang 或 Accept-Language 进行本地化（参见本地化）。

流式运行错误以 stream_error 事件的形式传递。失败的运行仍可能发送最终的 stream_ended 事件，其中 success: false 且设置了 stop_reason。非流式运行错误包含顶层的 usage 对象；费用不可用时，cost 为 null。

以下错误可能出现在任何端点：

各端点特有的错误将在相应端点下内联说明。

启动后运行错误

运行错误会在消息请求被接受之后出现。在流式传输模式下，它们表现为 stream_error 事件，随后可能跟随 success: false 的 stream_ended 事件。在非流式传输模式下，它们以 JSON 错误响应的形式返回，并附带下表所列的 HTTP 状态码。

分页

列出会话和列出消息使用基于游标的分页：

{
  "items": [],
  "next_cursor": "2026-05-19T11:15:00Z|ses_abc123",
  "has_more": true
}

将 next_cursor 作为 cursor 查询参数传入以获取下一页，传入时需对该值进行 URL 编码。当 has_more 为 false 时，表示没有更多结果。limit 超出 1-100 范围或游标无效时，将返回 400 bad_request。

本地化

所有端点都接受可选的 lang 查询参数，用于控制错误消息及任何本地化内容所使用的语言。

您可以在任意请求 URL 后附加 ?lang=xx：

POST /sessions?lang=zh
GET /sessions/ses_abc123/messages?lang=ja

支持的语言： en、zh、ja、ko、es、fr、de、it、pt、ru、id、th、vi

隐私与数据

Jenova 不会使用 API 提示词、输出内容、对话历史、上传的文件、智能体指令或知识库来训练 Jenova 的模型。

对于第三方模型提供方，Jenova 会使用商业 API 渠道、账户设置、合同约定或退出选项，以防止客户内容被用于训练提供方的模型。

Jenova 使用美国基础设施存储和处理 API 数据。第三方提供方可能在其他司法管辖区处理数据，具体如隐私政策和使用条款中所述。

有关完整详情，请参阅使用条款、隐私政策以及使用政策。

支持

• 控制面板： www.jenova.ai/platform
• 邮箱： [email protected]