新网关(源码指南)

新网关迁移说明

OneAster 新网关部署提交 f09a2d5 与 Go 构建版本 7ba12de+oneaster.0.1.0 的契约与接口指南。

从旧 Core 迁移到新网关(7ba12de+oneaster.0.1.0)

本页对照旧 Core 0.46.2 与已部署的 oneaster-gateway 提交 f09a2d5da1c9b6fbfd95ae4246080a8489d44564(线上版本 7ba12de+oneaster.0.1.0)。旧 Core OpenAPI(/api-reference/core-0462-openapi.json)与历史集成文档仅作为历史参考保留;当前首页、指南与公开接口参考均以新网关现行协议为准。即使路径同名,也不代表请求体、响应壳、账务结算或任务生命周期与旧 Core 相同。

推理、音频与异步任务差异

GET /v1/models 与 POST /v1/chat/completions 保留标准路径,但模型调用必须使用 model_name / id,不能把 display_name 当作 model 参数。图片编辑使用 POST /v1/images/edits(或登录态 POST /pg/images/edits),并支持 PR #46 新增的 complexity、markup、svg、frame_count、frame_duration_ms 字段。

旧 POST /v1/tasks 已改为按供应商插件划分的入口 POST /v1/tasks/kie(以及登录态 POST /pg/tasks/kie);旧 GET /v1/tasks/{id}/content 已改为先查询 GET /v1/tasks/{id}/artifacts(或 GET /pg/tasks/{task_id}/artifacts)获取产物列表,再携带 Bearer 凭据访问 GET /v1/tasks/{id}/artifacts/{artifact_key}/content(或 GET /pg/tasks/{task_id}/artifacts/{artifact_key}/content)。旧 /v1/audio/generations 系列没有等价路由:同步语音合成与识别使用 /v1/audio/speech、/v1/audio/transcriptions、/v1/audio/translations(及对应 /pg/audio/*),而 KIE Suno 音乐生成使用异步任务 POST /pg/tasks/kie(model 为 ai-music-api/generate,单次任务返回两条 MP3 音轨)。

旧 Core 的 Responses 文本存储、previous_response_id 续接及 DELETE /v1/responses/{id} 删除路由尚未迁移。旧任务 ID、历史媒体链接、PNG 归档与未决账务记录不能直接跨系统重放。任务状态 UNKNOWN 表示结果或账务尚未确认,绝不等于已失败或已退款;客户端应通过 GET /oneaster/v1/task-diagnostics/{task_id} 核查资金来源、登记状态与 settlement_receipt,不得自动重发。

账号、钱包与会话 Playground 差异

旧 /core/v1/* 账号、钱包、文本容量与旧会话 Playground 路由已停用:新网关使用原生 /api 处理登录与安全(含 PR #49 Google 原生 OAuth 登录支持 POST /api/oauth/state 与 POST /api/oauth/google),使用 /oneaster/v1 处理账户、钱包、Key(/oneaster/v1/keys)、模型目录、账务诊断与充值(含 PR #48 统一充值预览 GET /oneaster/v1/billing/preview 及 PR #47 Stripe 充值与到账记录),使用 /pg 处理登录态钱包直扣 Playground(含 Idempotency-Key 持久化意图与 GET /pg/requests/by-intent、GET /pg/requests/{request_id} 恢复接口),使用 /v1 处理个人推理 API Key 调用。旧 Core 会话不能替代 native access_token,切勿因支付页面回跳或未确定的生成结果而重复下单、重复生成。