接口概览

会话 Playground

OneAster 已实现接口、身份与调用契约。

登录会话与钱包

Core 0.40.0 提供面向已登录用户的会话 Playground 接口,不需要创建或粘贴个人 API Key。它使用本人账户分组和钱包,先预留费用,完成后按原报价或实际用量结算。前端页面及其同源 BFF 由用户端实现;本文档的“试一试”仍只使用 API Key,不采集会话凭据。

前端应通过同源 BFF 转发当前用户会话,并校验 Origin 与 CSRF;后端不提供通用跨域 CORS。POST /core/v1/playground/chat/completions、/responses、/messages 支持 JSON 或 SSE;文本成功响应使用对应协议,不包 Core 外壳。会话 Response 的 GET /core/v1/playground/responses/{id} 与 DELETE 仅操作本人 Playground 的本地续接上下文,不能续接个人 API Key 的历史。

图片和视频

POST /core/v1/playground/tasks 使用 kind、公开 model_name 和 input,异步创建图片或视频并返回 202 和任务 ID。POST /core/v1/playground/media-tasks 接收 multipart 的 task JSON 和单张 PNG image;上限 10 MiB、尺寸 1–4096,重试须保持同一源图 UUID、文件字节及原意图。参考视频仍需受控素材桥接。使用 GET /core/v1/tasks/{id} 查询本人任务,只有 billing_state=settled 且 artifact_available=true 才表示产物可用;PNG 通过 /core/v1/tasks/{id}/content 取得,视频可能提供临时链接,不承诺永久保存。具体型号和规格以账户目录为准。

原意图、费用与恢复

所有会话生成 POST 必须携带 Idempotency-Key;同一意图重试沿用原键和输入,修改输入或发起新生成才创建新键。断线或结果未知时用 GET /core/v1/playground/requests/by-intent?intent_id=原意图 查询,再按请求 ID 查账;404 不证明在途提交不会完成。unknown 或 reserved 表示尚待核账,不自动退款或重新生成。SSE HTTP 200 不代表最终成功,仍须检查终止事件、错误与账务;中止连接不代表供应商取消。金额以 balance_micro、reserved_micro 和 charge_micro 整数字符串为准,1 积分 = 10000 micro。