Skip to main content

​
基础信息

  • Base URL:https://agentapi.kira.art(浏览器直连,不经 kira-be)
  • 开发环境:http://localhost:8090
  • 认证:Bearer JWT(客户端)或 X-Internal-Key(服务器到服务器),见下
  • 响应格式:JSON;/stream 为 text/event-stream(SSE)
  • 设计风格:纯 REST,用 HTTP 状态码而非自造 string enum;无 v4 message 兼容
认证按路由分三种:agent 端点(/task、/stream、/messages、/thread/:id/current-task)挂 eitherAuth()(JWT 或 X-Internal-Key);POST /video/submit/:taskId 挂 supabaseAuth()(仅 JWT);GET /(根信息)与 GET /health 无认证(在根 app 上)。CORS 放行 localhost:3000、*.kira.art、*.poisson.art,并放过 Last-Event-ID 与 W3C trace header(traceparent / tracestate / baggage)。

​
认证

# 客户端(浏览器)
Authorization: Bearer <Supabase JWT>

# 服务器到服务器
X-Internal-Key: $INTERNAL_KEY
  • 客户端:Authorization: Bearer <Supabase JWT> —— hono/jwk 验 ES256,从 jwtPayload.sub 取 userId。
  • 服务器到服务器:X-Internal-Key: $INTERNAL_KEY。
  • agent 端点两条路径派发到同一中间件 eitherAuth();POST /video/submit/:taskId 单独挂 supabaseAuth()(只认 JWT,无 internal-key 路径);GET / 与 GET /health 无认证。
  • 资源归属校验:task.userId / messages.resource_id / video 行的 resource_id 必须等于当前 userId,否则 403 / 404。

​
Endpoint 索引

MethodPathAuth用途成功 / 失败
POST/taskeitherAuth启动 agent run(dedup lock + plan 校验 + 可选 rewind)201 {taskId} / 409 {taskId,reason:"running"} / 503 draining
GET/task/:taskIdeitherAuth查 task 状态200 TaskInfo / 404 / 403
DELETE/task/:taskIdeitherAuth停 task(幂等,发 abort 信号)204 / 404 / 403
GET/stream/:taskIdeitherAuthSSE 流(支持 Last-Event-ID 续读)200 text/event-stream / 404 / 403
GET/thread/:threadId/current-taskeitherAuththin lookup:thread 当前在途 task200 {task:null|{...}} / 403
GET/messages/:threadIdeitherAuththread 历史 messages(v5,升序)200 {messages:[...]} / 500
POST/video/submit/:taskIdJWT only重试失败视频生成(insufficient_*)200 {success:true} / 400 / 401 / 404 / 500
GET/none服务信息200 {service:"kira-agent",version}
GET/healthnone健康检查(draining 时 503)200 {status:"ok"} / 503 {status:"draining"}

​
HTTP 语义约定

状态码含义
201POST /task 成功创建并启动 run
409同 thread 已有在途 run(dedup lock 命中);body 带现役 taskId 供客户端续连
204DELETE /task 成功(幂等;task 仍 running 时才真正发 abort)
200查询类成功
404task 不存在(已过 TTL 或从未创建)
403资源不属于当前用户
401缺/无效 JWT
503实例正在 graceful drain(拒新 run / health 摘机)
GET /thread/:threadId/current-task 故意在”没有在途 task”时返 200 {task:null} 而不是 404 —— 这是查询当前状态而非取唯一资源,避免基于 status_code>=4xx 的告警被正常的”无任务”污染。

​
一次完整对话的调用顺序

1

打开 thread,检查在途 task

GET /thread/:threadId/current-task。若有在途 task,直接去 GET /stream/:taskId 续连;否则准备发新消息。
2

(可选)拉历史

GET /messages/:threadId 重建 UI(升序,v5 格式)。
3

发消息,启动 run

POST /task → 拿 201 {taskId}(或 409 时拿现役 taskId)。
4

开 SSE 流

GET /stream/:taskId。断线后带 Last-Event-ID 重连续读。
5

(可选)用户中止

DELETE /task/:taskId 发 abort 信号;stream 会收到 event: error 收尾。

​
参考