OpenAPI 接口文档

v1
管理 API Key

使用 REST API 创建图片和视频任务、查询模型能力并读取生成结果。公开接口版本固定为 v1。

快速开始

所有 /openapi/v1/* 接口使用 API Key 鉴权。请在请求头中发送 Bearer Token,不要从浏览器前端直接调用。

Base URL
https://open-api.mavowow.com
Authorization
Bearer fa_live_...
幂等要求:图片和视频生成必须携带 8–128 位 Idempotency-Key,可使用字母、数字、点、下划线、冒号和连字符。超时或 5xx 重试时复用原键。

图片生成

POST/openapi/v1/images/generations

一次请求创建一个图片任务,公开接口固定 count=1。

model
必填,图片模型 ID。
mode
必填:文生图使用 generate;提交 image_urls 进行编辑或参考图生成时使用 edit。
prompt
必填,至少 3 个非空白字符。
count
固定为 1。

任务查询

返回 201 Created 且 data.status 为 queued,表示任务已经成功创建并进入队列,不是错误。保存 data.id,随后按 Location 或任务查询接口轮询结果。

最小图片生成请求
curl -X POST 'https://open-api.mavowow.com/openapi/v1/images/generations' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: image-order-20260714-0001' \
  -d '{
    "model": "gemini-2.5-flash-image",
    "mode": "generate",
    "prompt": "一张柔和日光下的产品照片",
    "count": 1
  }'
201 Created
{ "data": { "id": "<TASK_ID>", "status": "queued" } }
创建成功:返回 201 Created 且 data.status 为 queued,表示任务已经成功创建并进入队列,不是错误。保存 data.id,随后按 Location 或任务查询接口轮询结果。

模型列表

模型和参数能力会持续变化。客户端应先读取模型列表,不要写死完整模型集合。

GET/openapi/v1/models

返回图片、视频模型以及每个模型支持的尺寸、比例、时长和分辨率等能力。

模型列表请求语言
curl 'https://open-api.mavowow.com/openapi/v1/models' \
  -H 'Authorization: Bearer YOUR_API_KEY'

图片生成

一次请求创建一个图片任务,公开接口固定 count=1。

POST/openapi/v1/images/generations

常用请求字段

model
必填,图片模型 ID。
mode
必填:文生图使用 generate;提交 image_urls 进行编辑或参考图生成时使用 edit。
prompt
必填,至少 3 个非空白字符。
count
固定为 1。
image_urls
编辑或参考图模式必填,必须为模型可访问的公网 HTTPS URL。
aspect_ratio
可选,图片宽高比。
size / resolution
可选,设置图片尺寸或分辨率。支持模型:size 用于 GPT Image 2、Nano Banana、Seedream、Qwen Image 2.0、Wan Image、Kling Image;resolution 用于 Grok Imagine、Grok Imagine Pro。
图片编辑请求
curl -X POST 'https://open-api.mavowow.com/openapi/v1/images/generations' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: image-edit-20260714-0001' \
  -d '{
    "model": "gemini-2.5-flash-image",
    "mode": "edit",
    "prompt": "保留主体,替换为摄影棚背景",
    "count": 1,
    "image_urls": ["https://cdn.example.com/input.jpg"],
    "aspect_ratio": "16:9"
  }'

视频生成

支持文字生成视频、图片生成视频,以及部分模型的视频编辑能力。

POST/openapi/v1/videos/generations

常用请求字段

model
必填,视频模型 ID。
video_mode
必填,例如 t2v、i2v_first、multimodal_ref 或 v2v_edit;必须命中模型支持的模式。
prompt
必填,至少 3 个非空白字符。
image_urls
可选,首帧、尾帧或参考图。
source_video_url
可选,视频编辑或扩展的源视频。
duration
可选,必须命中模型支持的时长。
resolution
可选,例如 720p。
ratio / aspect_ratio
可选,设置视频画面比例。支持模型:ratio 用于 Seedance、HappyHorse;aspect_ratio 用于 Grok Video、Kling Video、HappyHorse。
视频生成请求语言
curl -X POST 'https://open-api.mavowow.com/openapi/v1/videos/generations' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: video-order-20260714-0001' \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "video_mode": "t2v",
    "prompt": "城市夜景中的缓慢推进镜头",
    "duration": 10,
    "resolution": "720p",
    "ratio": "16:9"
  }'

任务查询

创建新任务返回 201 Created;幂等重放返回原任务和 200 OK。响应头包含 Location 与 Idempotent-Replayed。

  • queued排队中
  • processing生成中
  • succeeded已完成
  • failed失败
  • canceled已取消
GET/openapi/v1/tasks/{task_id}

查询当前账户的一个 OpenAPI 任务。成功后从 output 读取图片或视频地址。

任务状态查询
curl 'https://open-api.mavowow.com/openapi/v1/tasks/TASK_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY'
GET/openapi/v1/tasks

使用游标分页查询任务列表,任务读取接口的账户级限流为每分钟 120 次。

limit
每页数量。
cursor
上一页返回的分页游标。
type
image 或 video。
status
queued、processing、succeeded、failed 或 canceled。

错误处理

所有公开接口错误统一包含 error.code、message 和 request_id。联系支持时提供 request id 和 task id,不要提供完整 API Key。

  • 400
    invalid_request / invalid_media_url

    修正参数或素材地址,不要原样重试。

  • 401
    invalid_api_key

    检查密钥是否缺失、已重新生成或已撤销。

  • 402
    insufficient_points / membership_required

    充值点数或升级所需会员。

  • 404
    task_not_found

    核对任务 ID 和所属账户。

  • 409
    idempotency_key_reused

    不同请求更换幂等键;处理中则稍后重试。

  • 422
    validation_error

    根据 details 修正请求字段。

  • 429
    rate_limit / concurrent_limit

    遵循 Retry-After 或等待已有任务完成。

  • 5xx
    internal_error / service_unavailable

    退避重试,并继续使用原幂等键。

模型价格

OpenAPI 与网页端共用当前 Mavowow 账户的算力余额、会员权益和活动折扣。任务创建成功后从同一账户扣除算力;余额不足时返回 402,且不会创建任务。

图片模型

图片任务按张计费;尺寸和质量会影响部分模型的消耗。

GPT Image 2.5 Flare

gpt-image-2.5-flare
当前计费比例 50%
算力消耗明细
配置算力消耗
low · 1K原价:40;折扣价:20。算力 / 张
low · 2K原价:60;折扣价:30。算力 / 张
low · 4K原价:100;折扣价:50。算力 / 张
medium · 1K原价:80;折扣价:40。算力 / 张
medium · 2K原价:140;折扣价:70。算力 / 张
medium · 4K原价:240;折扣价:120。算力 / 张
high · 1K原价:280;折扣价:140。算力 / 张
high · 2K原价:540;折扣价:270。算力 / 张
high · 4K原价:900;折扣价:450。算力 / 张
xhigh · 1K原价:480;折扣价:240。算力 / 张
xhigh · 2K原价:960;折扣价:480。算力 / 张
xhigh · 4K原价:1,600;折扣价:800。算力 / 张
max · 1K原价:1,060;折扣价:530。算力 / 张
max · 2K原价:2,160;折扣价:1,080。算力 / 张
max · 4K原价:3,560;折扣价:1,780。算力 / 张
auto · 1K原价:1,060;折扣价:530。算力 / 张
auto · 2K原价:2,160;折扣价:1,080。算力 / 张
auto · 4K原价:3,560;折扣价:1,780。算力 / 张

视频模型

视频任务按生成秒数计费。下表严格按模型配置和正式计费函数,展示各模型默认 5 秒任务的实际算力消耗;分辨率、音频和视频输入方式会影响最终消耗。

Grok Video

grok-video-3
算力消耗明细
配置算力消耗
基础生成 · 480p · 5 秒500算力 / 次
基础生成 · 720p · 5 秒750算力 / 次

常见问题

Mavowow API 参考文档说明可用端点、请求参数、响应结构与错误码,并随版本更新;接入时以参考文档当前内容为准。