API 文档v1.0

快速开始

整个流程很简单：创建密钥，提交任务，等待完成，再下载 SVG。文档公开可读，实际调用需要 API Key。

1. 01在 API 管理页 创建密钥，并保存为服务端环境变量 MOMOVECTOR_API_KEY。
2. 02设置地址 MOMOVECTOR_BASE_URL；每个新任务生成一次 MOMOVECTOR_REQUEST_ID，重试时保留。
3. 03提交后保存 job.id，每 2–3 秒查询状态，完成后携带密钥下载。

export MOMOVECTOR_BASE_URL='https://momovector.com'
# 每个新任务只生成一次；网络重试不要重新执行下面这行
export MOMOVECTOR_REQUEST_ID="$(python3 -c 'import uuid; print(uuid.uuid4())')"

curl 'https://momovector.com/api/v1/generations' \
  -H "Authorization: Bearer $MOMOVECTOR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $MOMOVECTOR_REQUEST_ID" \
  -d '{"mode":"text","prompt":"一只可爱的小橘猫","style":"playful"}'

# 把响应中的 job.id 设置为 JOB_ID
export JOB_ID='替换为实际任务 ID'
curl "$MOMOVECTOR_BASE_URL/api/v1/generations/$JOB_ID" \
  -H "Authorization: Bearer $MOMOVECTOR_API_KEY"

# 等待 status 为 completed 后下载
curl "$MOMOVECTOR_BASE_URL/api/v1/generations/$JOB_ID/file" \
  -H "Authorization: Bearer $MOMOVECTOR_API_KEY" \
  --output artwork.svg

鉴权与密钥

所有数据接口都要求请求头 Authorization: Bearer <API_KEY>。密钥只能在创建时查看一次；可设置有效期，并在管理页随时撤销。

Authorization: Bearer mv_sk_...
Content-Type: application/json
Idempotency-Key: 仅提交新任务时必填

• 默认有效期为 90 天，可选 30、90、365 天或永久。每账户最多 10 个有效密钥。
• 密钥用于生成、查询和下载本账户作品；不能用于购买额度、删除作品或管理其他密钥。
• 公共 API 不接受 Cookie 或 URL 参数代替 Bearer Key，面向服务端和脚本调用。
• 正式环境使用 HTTPS；密钥存放在服务端环境变量中，不放进前端代码。
• 撤销会阻止后续鉴权；已经提交的任务仍会完成，作品会留在原账户。

创建生成任务

文字与图片共用同一个接口。请求体为 JSON，成功返回 202 Accepted，扣除本次额度并创建异步任务。

{
  "mode": "text",
  "prompt": "一只可爱的小橘猫",
  "style": "playful"
}

{
  "job": {
    "id": "2a357e9c-a431-42c4-9d73-bfb2b265712a",
    "mode": "text",
    "prompt": "一只可爱的小橘猫",
    "style": "playful",
    "status": "queued",
    "cost": 2,
    "source": "api",
    "demo": false,
    "error": null,
    "createdAt": "2026-09-26T20:00:00.000Z",
    "url": null
  }
}

响应头 Location 是任务查询地址，Retry-After: 2 建议两秒后查询。202 表示任务已接受，并非已经完成。

风格参考图

通过 styleReferences 提供配色、线条和视觉风格参考。文字描述或 image 仍决定主体内容，Logo 主色仍优先。参考图不增加站内额度消耗。

{
  "mode": "text",
  "prompt": "一只坐在月亮上的狐狸",
  "style": "flat",
  "styleReferences": [
    "https://images.example.com/style.png",
    "data:image/webp;base64,..."
  ]
}

• 最多 2 张，可混合文件与链接。上传文件支持 PNG、JPG、WebP，解码后每张最多 2 MiB。
• 链接需为公开可访问的 HTTPS 图片直链，不能是网页或本地地址。链接由模型服务读取，处理期间需保持可用；外部图片不会被 MomoVector 归档。
• 修改参考内容或顺序需要新的 Idempotency-Key。相同内容重试不会重复扣费。
• 响应 styleReferences 中 kind 为 upload 的 url 需同账户 Bearer 鉴权，可通过 GET /api/v1/generations/{id}/references/{index} 读取；kind 为 url 的地址为原始外部链接，不应向该地址发送 MomoVector API Key。
• 上传参考图会随作品私有保存，删除作品时同时删除。Python 示例支持重复使用 --reference style.png 或 --reference https://…。

手绘草图生成 Logo

将画布导出的 PNG 或已有草图作为 image，使用 purpose=logo。每次消耗 1 额度，失败返还；不需要文字生成步骤。仅适用于已启用手绘 Logo 的服务。

{
  "mode": "image",
  "purpose": "logo",
  "style": "minimal",
  "primaryColor": "#24483F",
  "prompt": "山野咖啡店，保留山峰轮廓，简洁有力量",
  "image": "data:image/png;base64,..."
}

style 固定为 minimal。prompt 选填，最多 1200 字；primaryColor 必须是六位十六进制颜色，仅在 logo 模式中使用。主色是生成指导，实际颜色可能有差异。

响应中的 purpose、primaryColor 和 inputUrl 记录本次创作。使用同账户 Bearer Key 请求 GET /api/v1/generations/{id}/input 可读取原始草图；完成后仍通过 /file 下载 SVG。

python momovector_api.py --image sketch.png --purpose logo --primary-color '#24483F' --output logo.svg

查询任务状态

id 为提交响应中的 job.id。只允许读取本账户任务。

{
  "job": {
    "id": "2a357e9c-a431-42c4-9d73-bfb2b265712a",
    "mode": "text",
    "prompt": "一只可爱的小橘猫",
    "style": "playful",
    "status": "completed",
    "cost": 2,
    "source": "api",
    "demo": false,
    "error": null,
    "createdAt": "2026-09-26T20:00:00.000Z",
    "url": "/api/v1/generations/2a357e9c-a431-42c4-9d73-bfb2b265712a/file"
  }
}

下载 SVG

任务 completed 后返回 SVG 文件，类型为 image/svg+xml; charset=utf-8，附带下载文件名。此地址不是公开分享链接，每次下载都需要 Bearer Key。

curl "$MOMOVECTOR_BASE_URL/api/v1/generations/$JOB_ID/file" \
  -H "Authorization: Bearer $MOMOVECTOR_API_KEY" \
  --output artwork.svg

未成功完成返回 409 result_not_ready；不存在、已删除或不属于当前账户的作品返回 404 not_found。

获取历史记录

按创建时间倒序返回同一账户的网页与 API 作品，每页 24 条。作品中的 source 可区分创建入口。

curl "$MOMOVECTOR_BASE_URL/api/v1/generations?offset=0" \
  -H "Authorization: Bearer $MOMOVECTOR_API_KEY"

{
  "items": [
    {
      "id": "2a357e9c-a431-42c4-9d73-bfb2b265712a",
      "mode": "text",
      "prompt": "一只可爱的小橘猫",
      "style": "playful",
      "status": "completed",
      "cost": 2,
      "source": "api",
      "demo": false,
      "error": null,
      "createdAt": "2026-09-26T20:00:00.000Z",
      "url": "/api/v1/generations/2a357e9c-a431-42c4-9d73-bfb2b265712a/file"
    }
  ],
  "hasMore": false,
  "nextOffset": 24
}

hasMore 为 false 时停止翻页。items 中每项都使用相同的 job 字段格式。

查询账户额度

返回可用额度、当前生成单价、演示状态和账户调用限制。网页购买的额度可直接用于 API。

curl "$MOMOVECTOR_BASE_URL/api/v1/credits" \
  -H "Authorization: Bearer $MOMOVECTOR_API_KEY"

{
  "balance": 60,
  "costs": {
    "text": 2,
    "image": 1
  },
  "demo": false,
  "limits": {
    "requestsPerMinute": 60,
    "activeKeys": 10,
    "concurrentJobs": 4
  }
}

错误码与处理

所有公共 API 错误都返回 HTTP 状态码和统一 JSON。排查问题时保留 error.requestId，它与响应头 X-Request-Id 一致。

{
  "error": {
    "code": "insufficient_credits",
    "message": "额度不足，请在网页购买额度后重试。",
    "requestId": "fdba965d-0c4c-439b-81d1-c2bc3db23ae0"
  }
}

计费、限流与重试

每账户每个 UTC 自然分钟最多 60 次公共 API 请求，所有密钥共用；提交、查询和下载都计入。OpenAPI 文档不计入。网页与 API 共用最多 4 个同时进行的生成。

• 同一任务的网络重试始终使用原 Idempotency-Key 和相同内容；同一账户的所有密钥和网页共享幂等范围。
• 同一标识被用于不同内容、已删除作品或没有指纹的旧任务时，返回 409 idempotency_conflict。
• 遇到 429 遵守 Retry-After；遇到网络或 5xx 错误，进行有间隔、有次数上限的重试。
• 成功接受任务后保留 job.id。生成失败自动返还额度；重新创作则使用新的请求标识。