模型调用 ID 与开始推理
以下契约对应部署提交 f09a2d5da1c9b6fbfd95ae4246080a8489d44564,Go 构建版本为 7ba12de+oneaster.0.1.0。调用 /v1 时使用个人推理 Key(ONEASTER_API_KEY),调用 /pg 时使用登录 access_token(ONEASTER_ACCESS_TOKEN)。所有生成请求的 model 字段必须传入模型目录中的调用标识符(/oneaster/v1/model-catalog 中的 model_name,或 /v1/models 中的 id),绝不能把管理员可修改的展示名称 display_name 当成 model 参数传入。
curl "$BASE_URL/v1/models" -H "Authorization: Bearer $ONEASTER_API_KEY"
curl "$BASE_URL/v1/chat/completions" -H "Authorization: Bearer $ONEASTER_API_KEY" -H 'Content-Type: application/json' -d '{"model":"YOUR_MODEL_NAME","messages":[{"role":"user","content":"Hello"}],"stream":false}'
文本协议(/v1 与 /pg)
POST /v1/chat/completions、POST /v1/responses、POST /v1/messages 以及对应的 POST /pg/chat/completions、POST /pg/responses、POST /pg/messages 分别遵循 OpenAI Chat Completions、OpenAI Responses 和 Anthropic Messages 协议,支持 JSON、SSE 流式输出与工具调用;GET /v1/responses/{response_id} 与 GET /pg/responses/{response_id} 按响应 ID 查询。/v1 推理接口不启用 /pg 的持久化意图存储,不要将 Idempotency-Key 视为 /v1/chat/completions 的必填头。旧 Core 的 Responses 历史存储、previous_response_id 续接及 DELETE /v1/responses/{id} 生命周期尚未迁移。
图片生成、编辑与 PR #46 扩展参数
POST /v1/images/generations 与 POST /pg/images/generations 接收 JSON;POST /v1/images/edits 与 POST /pg/images/edits 同时支持 JSON(image 或 images 传 URL / Data URL)与 multipart/form-data 文件上传。PR #46 在图片生成与编辑请求中新增以下可选扩展参数:complexity(string,复杂度提示)、markup(string 或 multipart 文件,标记/结构化输入)、svg(boolean,是否请求 SVG 输出)、frame_count(integer,序列帧数量)与 frame_duration_ms(integer,单帧时长毫秒),并继续支持 aspect_ratio、resolution、seed、negative_prompt、output_format、background、moderation、output_compression、watermark、prompt_upsampling、safety_tolerance。具体参数生效范围取决于所选模型与上游渠道。
标准视频与受保护内容下载
POST /v1/videos 与 POST /pg/videos 创建异步视频任务,GET /v1/videos/{task_id} 与 GET /pg/videos/{task_id} 查询状态,GET 或 HEAD /v1/videos/{task_id}/content 与 /pg/videos/{task_id}/content 下载 MP4 二进制流。下载受保护内容必须携带 Authorization: Bearer 凭据,浏览器原生 video 或 audio 标签不能直接裸链请求受保护地址;前端应通过 fetch 携带 Bearer 拉取二进制响应,再转为 Blob URL 播放。
同步语音接口与 KIE Suno 异步音乐任务(PR #42)
标准语音接口与异步音乐任务采用完全不同的调用方式,网关不提供旧 /v1/audio/generations 或 /pg/audio/generations 别名。
第一类是同步音频接口:POST /v1/audio/speech 与 POST /pg/audio/speech 接收 JSON(model、input、voice,可选 response_format 如 mp3/wav/opus/aac/flac/pcm、speed、stream_format 如 audio/sse),直接返回音频二进制字节流或 SSE 音频分片(在 /pg/requests/by-intent 恢复接口中,不大于 4 MiB 的二进制语音以 response.encoding = "base64" 返回)。POST /v1/audio/transcriptions、POST /v1/audio/translations、POST /pg/audio/transcriptions、POST /pg/audio/translations 均采用 multipart/form-data 上传音频文件(必填 model 与 file,单文件上限 50 MiB)。
curl --request POST "https://api.oneaster.ai/pg/audio/transcriptions" \ --header "Authorization: Bearer $ONEASTER_ACCESS_TOKEN" \ --header "Idempotency-Key: $ONEASTER_INTENT" \ --form "model=YOUR_AUDIO_MODEL_NAME" \ --form "[email protected];type=audio/wav"
第二类是 KIE Suno 异步音乐生成:使用 POST /v1/tasks/kie(API Key)或 POST /pg/tasks/kie(登录 access_token)。在 /pg/tasks/kie 中,请求体固定使用调用 ID model: "ai-music-api/generate"、n: 1、prompt(不超过 3000 字符)以及 audio 对象(mode: "music",music_version 支持 "V6"、"V6_MINI"、"V6_WILD" 默认 "V6",custom_mode 布尔值,instrumental 布尔值,style 不超过 1000 字符,lyrics 不超过 5000 字符,style 与 lyrics 至少一项非空,title 不超过 80 字符且在 custom_mode=true 时必填,duration 省略或 0 表示不指定,非零值为 10 至 360 秒整数且仅在 custom_mode=true 时允许)。
curl --request POST "https://api.oneaster.ai/pg/tasks/kie" \
--header "Authorization: Bearer $ONEASTER_ACCESS_TOKEN" \
--header "Idempotency-Key: $ONEASTER_INTENT" \
--header "Content-Type: application/json" \
--data '{"model":"ai-music-api/generate","prompt":"Warm lo-fi piano loop for late night coding","n":1,"audio":{"mode":"music","music_version":"V6","custom_mode":false,"instrumental":true,"style":"Warm lo-fi piano"}}'
一次 Suno 音乐生成成功后会产出 2 条独立 MP3 音轨(产物 key 分别为 audio-0 与 audio-1)。客户端提交后保存返回的 task_id,每 3 至 5 秒轮询 GET /pg/tasks/{task_id}(或 GET /v1/tasks/{id}),终态后调用 GET /pg/tasks/{task_id}/artifacts(或 GET /v1/tasks/{id}/artifacts)读取音轨列表(含 key、type、mime_type、content_url;不提供曲名、时长或封面字段),再携带 Authorization: Bearer 调用 GET /pg/tasks/{task_id}/artifacts/{artifact_key}/content 下载对应 MP3 字节流并生成 Blob URL。通用任务状态包含 NOT_START、SUBMITTED、QUEUED、IN_PROGRESS、SUCCESS、FAILURE、UNKNOWN;遇到 UNKNOWN 绝不能当作失败退款或自动重发。