API REF

提交生成任务

向平台提交一个生成任务。平台按 API Key 上配置的渠道策略自动选择上游渠道并完成计费，同步任务当场返回结果，异步任务返回任务句柄供轮询。

接口基本信息

项目	说明
接口用途	提交对话 / 图像 / 视频等生成任务
请求方式	`POST https://api.mozhiai.net/v1/generations`
认证方式	`Authorization: Bearer YOUR_API_KEY`
请求体	`Content-Type: application/json`
计费	成功后按响应中的 cost_amount 扣费并累计密钥额度

请求体字段

字段	类型	必填	说明
`model_id`	string	是	模型 ID。必须传字符串（雪花 ID），从 GET /v1/models 获取
`prompt`	string	否	提示词 / 输入内容
`input_file_urls`	string[]	否	输入文件 URL 列表（图生图、图生视频等场景传入可公网访问的文件地址）
`params`	object	否	模型参数，键为模型详情接口 parameters 里的 param_key，不传用默认值

开放 API 不接受 strategy / channel_group_id 字段——渠道路由策略由 API Key 自身配置决定（见 API Key 认证）。

请求示例

cURL

curl -X POST https://api.mozhiai.net/v1/generations \
  -H "Authorization: Bearer $MOZHIAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "1234567890",
    "prompt": "一只戴宇航头盔的柯基，赛博朋克风格",
    "input_file_urls": [],
    "params": {
      "size": "1024x1024"
    }
  }'

同步与异步

提交后立即返回任务对象，根据响应里的 status 区分两种情况：

场景	返回状态	后续动作
同步任务（多数对话类模型）	`completed`	结果已在 output_result 中，直接使用，无需轮询
异步任务（图像 / 视频等耗时模型）	`pending` / `processing`	用返回的 id 轮询 GET /v1/generations/:id，直至终态

响应示例

Response（异步任务，刚提交）

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "1234567890123456",
    "conversation_id": "1234567890123456",
    "group_sequence": 1,
    "model_id": "1234567890",
    "model_type": "image",
    "input_content": "一只戴宇航头盔的柯基，赛博朋克风格",
    "status": "processing",
    "progress": 0,
    "cost_amount": 0,
    "submitted_at": "2026-07-24T10:30:00+08:00"
  },
  "trace_id": "..."
}

响应字段（任务对象）

字段	类型	说明
`id`	string	任务 ID（字符串），轮询时使用
`conversation_id`	string	会话组 ID，开放 API 单任务模式下与任务 ID 相同
`group_sequence`	int	轮次序号，开放 API 恒为 1
`model_id`	string	本次调用的模型 ID
`model_type`	string	模型类型（chat / image / video 等）
`input_content`	string	输入内容（prompt）
`status`	string	任务状态：pending / processing / completed / failed / cancelled
`progress`	int	进度 0–100
`error_message`	string	失败原因，仅失败时出现
`cover_url`	string	结果封面图，视模型而定
`output_result`	object	生成结果，结构因模型 / 厂商而异，仅成功时出现
`cost_amount`	float64	本次计费金额（元），同步任务提交响应里即有值
`submitted_at`	string	提交时间（RFC3339）
`completed_at`	string	完成时间（RFC3339），仅终态时出现

错误码

HTTP	错误码	说明	处理建议
400	`100001`	请求参数不合法（如缺 model_id）	检查请求体
400	`130005`	模型参数不合法（params 校验失败）	对照模型详情的 parameters 修正
401	`190002`	API Key 缺失、无效或已吊销	检查密钥
402	`190003`	API Key 额度已用尽	调高额度或换密钥
402	`120001`	账户余额不足	充值后重试
404	`130001`	模型不存在或已下线	重新拉取模型列表
502	`130004`	上游渠道调用失败	指数退避重试
503	`130003`	暂无可用渠道	稍后重试

调用示例

Python（提交 + 轮询闭环）

import os, time, requests

BASE = "https://api.mozhiai.net/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['MOZHIAI_API_KEY']}"}

# 提交任务
resp = requests.post(f"{BASE}/generations", headers=HEADERS, json={
    "model_id": "1234567890",
    "prompt": "一只戴宇航头盔的柯基，赛博朋克风格",
    "params": {"size": "1024x1024"},
})
task = resp.json()["data"]

# 同步任务直接完成；异步任务轮询（间隔 >= 3 秒）
while task["status"] in ("pending", "processing"):
    time.sleep(3)
    task = requests.get(
        f"{BASE}/generations/{task['id']}", headers=HEADERS
    ).json()["data"]

if task["status"] == "completed":
    print(task["output_result"])
else:
    print("失败：", task.get("error_message"))