概览

Base URL

请使用以下地址作为 API 请求的 Base URL，不要带末尾斜杠。

地址：https://testing.amags.keplerjai.com

完整请求 URL = 地址 + 路径。路径以 /v1 开头，例如 /v1/images/generations、/v1/tasks/:id。即：图像生成为 POST https://testing.amags.keplerjai.com/v1/images/generations，任务查询为 GET https://testing.amags.keplerjai.com/v1/tasks/:id。下文与图像/视频等文档中的示例均使用该地址。

通用约定

开放 API 使用 API Key 作为 Bearer Token，所有接口路径以 /v1 为前缀。异步任务类接口（如图片、视频生成）提交后返回 task_id，需通过 任务查询接口 轮询状态并获取结果链接。

请求头

• Authorization必填，Bearer <API_KEY>，API Key 在「API 密钥」中创建后获得
• Content-Typeapplication/json（POST/PUT 等带 body 的请求）
• Idempotency-Key选填，创建类请求建议携带唯一字符串（如 UUID），用于防止重复提交

统一响应格式

接口返回 JSON，顶层包含 resultCode、resultMsg。成功时 resultCode 为 OK，业务数据与 resultCode/resultMsg 同级（如 task_id、task）；失败时 resultCode 非 OK，resultMsg 为错误说明。

任务查询

GET /v1/tasks/:id，路径参数 id 为创建任务返回的 task_id。响应中 task.status 为 succeeded 时 task.resultUrl 即为结果文件地址；failed 表示任务失败；queued/running 需继续轮询。详见下方「任务查询与取消」。

模型与类型对照

创建图片/视频任务时，model 传 模型名称，与模型列表或接口 GET /api/amags/model/list 返回的 name 完全一致。

任务查询与取消

图片、视频等异步任务创建后返回 task_id，可通过以下接口查询状态、获取结果或取消任务。

根据 ID 获取任务

GET /v1/tasks/:id，路径参数 id 为 task_id。响应示例：{"resultCode":"OK","task":{...}}，task 含 status、resultUrl、resultUrls、durationMs 等。

任务列表（分页）

GET/v1/tasks，查询参数：page、pageSize、status（queued|running|succeeded|failed|canceled）、type（image|video）。响应含 taskArr、pagination（total、current、pageSize）。

取消任务

POST /v1/tasks/:id/cancel，路径参数 id 为 task_id。

任务状态

• queued排队中
• running执行中
• succeeded成功，含 resultUrl / resultUrls
• failed失败，见 errorCode、errorMessage
• canceled已取消

视频任务成功后，平台可能先将供应商临时地址写入 resultUrl，转存到 OSS 后再更新为平台地址；转存进度见任务字段 resultStorageStatus（transferring / completed / failed）及 resultStorageError。

旗舰模型

模型概览

视频模型

图像模型

推荐阅读