Skip to main content

Documentation Index

Fetch the complete documentation index at: https://tech.illasoft.com/llms.txt

Use this file to discover all available pages before exploring further.

​
基础信息

  • Base URL：https://api.kira.art
  • 开发环境：http://localhost:8080
  • 认证方式：Bearer JWT（Supabase Auth）
  • 响应格式：JSON
  • OpenAPI spec：openapi.yaml
Billing 路由已迁移：订阅/Booster/Portal/Webhook 全部走 billing.kira.art（详见 Kira SG Billing）。kira-be 只保留使用时的 credit 扣减和用户删除时的 Stripe customer 清理。

​
认证

Authorization: Bearer <supabase-jwt>
  • 受保护路由用 supabaseAuth() 中间件验证 ES256 JWT
  • 公开但可带 token 的路由用 optionalSupabaseAuth()（验证失败也继续）
  • Sentry 用户上下文自动注入 jwtPayload.sub / email

​
路由前缀

前缀用途认证
/agentAI 对话、SSE 流、task 保存、stream 重连JWT
/thread线程 CRUD、timeline 聚合JWT
/userProfile 查询/更新、头像 CSAM、账户删除JWT / 密码保护
/feed社交 feed 列表、查询、featured、删除可选 JWT
/publishImage / Video / Audio 三路发布JWT
/likeFeed 点赞JWT + 可选
/filter预设滤镜 + 用户收藏JWT
/imageget / delete / CSAM check可选
/images批量查询无
/videotask / info / submit / initialize / uploadJWT
/musictask / info / submit / initialize / uploadJWT
/rewindcheck / versions / messages无
/version/versions/:threadId 版本聚合JWT
/download带水印图片/视频下载JWT
/maildaily / account-deletion 邮件发送密码保护
/supportFront Chat hash / 账户删除调度JWT
/sitemapusers / feeds 爬虫无
/opCMS 代理：announcement / homecards/v2 / trending无（i18n by Accept-Language）
/health健康检查无

​
完整路由清单

​
Agent（AI 对话）

MethodPath说明
GET/agent/chatMessages/:threadId消息历史（v4→v5 自动迁移）
GET/agent/rewind/:threadId/:messageIdrewind 点之前的消息
POST/agent/streamingSSE 流式 AI 对话（核心）
POST/agent/task保存 AI 生成的版本 + 派发 video/music Inngest events
GET/agent/task/:threadId/status查询 agent 运行状态
POST/agent/task/:threadId/stop中止当前 agent（AbortController + Redis cancel flag）
GET/agent/stream/:threadIdSSE 重连，从 Redis stream 重放 chunks

​
Thread

MethodPath说明
POST/thread/创建线程；Mistral 生成标题；首消息触发非阻塞 CSAM
GET/thread/threads用户线程列表
DELETE/thread/:threadId删除线程；异步取消 video/music 任务 + 清理存储
GET/thread/timelines分页 5 条/页；服务端 mixed-media 聚合

​
User

MethodPath说明
GET/user/profile当前用户完整 profile（含 credits）
PUT/user/profile更新；头像 CSAM（451 错误）
GET/user/profile/:userId公开 profile
GET/user/:userId/feed用户发布的 feed 分页
GET/user/:userId/liked用户点赞的 feed 分页
GET/user/referral-info推荐信息
GET/user/authBg登录页背景图
DELETE/user/密码保护；删除 Stripe customer + PostHog + Supabase 账号

​
Feed / Publish / Like

MethodPath说明
GET/feed/分页 20/页；nsfw 过滤
GET/feed/featured精选（无分页）
GET/feed/:id单条查询
DELETE/feed/:id删除 + LanceDB embedding 清理
POST/publish/Image 发布（默认 media_type=null）
POST/publish/videoVideo 发布；缩略图审核
POST/publish/audioAudio 发布；cover+lyrics+prompt 三路 CSAM
GET/like/:feedId查询是否点赞
PUT/like/:feedId点赞（upsert）
DELETE/like/:feedId取消点赞

​
Image / Images

MethodPath说明
GET/image/:imageId查询图片 + 签名 URL
DELETE/image/:imageId删除（含所有派生）
POST/image/check/:imageIdCSAM 检查；命中返回 451 + 删除
GET/images/:imageIds批量查询（逗号分隔）

​
Video / Music

MethodPath说明
GET/video/task/:taskId视频任务状态 + Signed URL
GET/video/info/:videoIds批量查询（逗号分隔）
POST/video/submit/:taskId余额/plan 恢复后重发 Inngest
POST/video/initialize占位符任务（video edit/extend 的 source）
DELETE/video/upload/:taskId删除媒体文件
GET/music/task/:taskId音乐任务状态
GET/music/info/:audioIds批量查询
POST/music/submit/:taskId恢复后重发
POST/music/initialize占位符任务
DELETE/music/upload/:taskId删除

​
Rewind / Version / Download

MethodPath说明
GET/rewind/check/:originImageId是否有历史版本（nsfw 线程阻断）
GET/rewind/versions/:feedIdFeed 对应的版本历史
GET/rewind/messages/:feedId原始消息
GET/version/versions/:threadId线程所有版本（JWT）
POST/download/带水印图片下载（生成或缓存）
POST/download/video带水印视频下载

​
Filter

MethodPath说明
GET/filter/preset预设滤镜列表
POST/filter/like收藏滤镜（upsert）
DELETE/filter/like/:filterId取消收藏
GET/filter/liked用户收藏列表

​
Support / Mail

MethodPath说明
GET/support/hashFront Chat HMAC-SHA256(userId)
POST/support/delete-account30 天账户删除调度 + 立即邮件
GET/support/deletion-status查询调度状态
POST/support/cancel-delete-account取消调度 + 确认邮件
POST/mail/daily密码保护；free 用户每日邮件
POST/mail/account-deletion密码保护；账户删除各阶段邮件

​
CMS Proxy / Sitemap / Health

MethodPath说明
GET/op/announcement从 CMS 读公告，按 Accept-Language 选语言
GET/op/homecards/v2Home Cards V2（Featured/Image/Video/Audio）
GET/op/trendingTrending 区
GET/sitemap/users用户 ID（≤10000）
GET/sitemap/feedsFeed ID（排除 nsfw）
GET/health{ status: "ok" }

​
通用响应

​
成功

{ "message": "ok" }
部分端点返回具体对象（feed、thread、image、video、audio、profile 等），参见各 API 页面。

​
错误

{ "message": "Error description" }
状态码含义
200成功
400参数错误
401未授权（JWT 无效/过期）
403禁止访问（plan 不够、未拥有资源）
404资源不存在
451CSAM 命中（图片/头像）
500服务器错误

​
CORS

  • https://*.kira.art、https://kira.art、https://op.kira.art
  • 开发环境允许所有来源

​
异步任务和实时推送

所有视频/音乐生成通过 Inngest 派发（kira-be/src/lib/tasks.ts），Worker 回调通过 Centrifugo 推送：
  • Channel：{userId}/{threadId}#{userId}
  • Event type：video_status / audio_status
详见 Kira Inngest。

​
限流

当前无全局 rate limit，业务层面的约束：
  • 用户 plan → credit 余额
  • Inngest per-user-per-tool concurrency = 1（同工具串行）
  • CSAM 阻断：命中后不扣费但后续请求仍会被审核

​
Billing 和 Credits

职责位置
订阅 / Booster / Portal / Webhookkira-sg-billing
使用时 credit 扣减（RPC deduct_credits）kira-be src/ai/libs/billing.ts
删除用户清理 Stripe customerkira-be src/hono/user/index.ts:33-88

​
参考