Skip to main content
使用 Agent API,你可以从自己的应用中向 Krea Agent 下达任务。请求和响应均使用 camelCase 格式的 JSON 字段。Agent 在后台工作,你的应用可以读取其进度和结果。
Agent 在后台工作。它不会提出问题,费用和权限确认会被自动批准。请在提示词中写明所有要求和约束。提交前请仔细检查任务。

认证、访问权限与计费

向 https://api.krea.ai 发送的每个请求都需携带 Authorization: Bearer KREA_API_KEY。个人、服务和旧版 API 密钥均使用标准的公共 API 认证。 你只能读取或继续由已认证调用方在已认证工作区中拥有的会话。仅知道会话 ID 并不能获得访问权限。Krea 文件附件也必须可供该调用方在该工作区中访问。
Agent 的每一轮使用工作区的计算单元余额,不使用 API 余额。Agent 套餐权益和 Free 套餐的消息限制仍然适用。请参阅 Agent 套餐、访问权限与积分。
每个响应都包含一个 url,具备相应账户和工作区访问权限时,可通过它在 Krea 应用中打开该会话。

启动会话并等待结果

请先在环境中设置 KREA_API_KEY。可选择 Bash(配合 curl 和 jq)、Python(配合 requests),或 Node.js(使用内置 fetch 或 Krea SDK)。
1

提交第一轮

省略 sessionId 即可创建会话。保存返回的 sessionId 和 runId。响应会立即返回,并带有 status: "running"。
2

等待这一轮

将两个 ID 都传给 wait-for-session。如果 timedOut 为 true,请使用相同的 ID 再次调用。超时不会取消该轮。
3

读取结果

当 finished 为 true 时检查 status。查看 text、media 以及可能存在的 error,或打开返回的 url。
使用 Python 时,请通过 pip install requests 安装 requests。使用 Node.js 时,请使用 Node.js 22+,并将示例保存为 example.mjs。SDK 示例需要 npm install @krea-ai/sdk,并使用 requestRaw 调用 HTTP 端点。 这些示例会提交一条消息并最多等待五分钟。遇到 HTTP 错误以及失败或已取消的轮次时会停止。它们从不自动重试发送。如果发送请求超时,请先在 Krea 中检查该会话再重新提交;第一个请求可能已经启动了一轮。 等待时间预算用尽后,该轮仍会在后台继续运行。请保存打印出的会话 ID 和运行 ID,以便稍后继续等待。 timeoutSeconds 是 1 到 300 之间的整数,默认值为 60。请让 HTTP 客户端的超时时间长于请求的等待时间。发送后等待时,请始终传入最新的 runId,以免将上一轮的终止状态误认为新一轮的状态。

不等待直接读取

使用 GET /agent/session/{sessionId} 获取当前会话的快照:
cURL

继续会话

该轮完成后,使用其 sessionId 发送另一条消息:
cURL
一个会话一次只运行一轮。在某一轮运行期间发送另一条消息,会返回 409 和 code: "conflict"。

输入与附件

send-message 接受以下字段。完整的模型枚举和 schema 请参阅参考文档。 附件的 url 接受可访问的 HTTP(S) URL,或已授权的 Krea Files URI,例如 file:550e8400-e29b-41d4-a716-446655440000。可选的 name 和 contentType 为去除首尾空白后非空、最多 255 个字符的字符串。不支持调用方本地路径和 OpenAI 的 file_ ID。请先传输实际文件;提示词文本中的 ID 不会传输其内容。 Agent 不会继承你的应用中的对话或附件。请附加无法通过其他方式访问的参考文件。对于提示词中、现有 Krea 上下文中或之前会话文件中已可用的 URL,无需重复提供。

会话结果

send-message 返回 sessionId、threadId、runId、status(始终为 "running")和 url。 GET /agent/session/{sessionId} 和 wait-for-session 返回以下会话视图。只有 wait-for-session 会额外返回必填字段 timedOut。 每个 media 项可以表示一次生成(jobId 和可选的 mediaKind:image、video、audio 或 3d)、重新托管的媒体(url,可选 mimeType),或一个 Krea 文件(uri、name、mimeType)。可通过 GET /jobs/{jobId} 获取生成详情。你可以将 Krea 文件 URI 复用为附件,或打开会话的 url 查看其文件。轮次仍在运行时,媒体也可能已经出现。

错误

端点错误使用 { "error": "...", "code": "...", "allowedModels": ["..."] } 格式。只有 error 是必填的。提交后失败的轮次则会在成功的会话响应中显示为 status: "failed"。