面向开发者

CoverMagic API & MCP

让任何 agent、工作流或代码库自动生成爆款封面。一份积分通用——网页、REST API、MCP 共享。

快速开始

注册并购买积分（注册即送 3 次免费生成）。
前往账户 → API Keys，创建一个 Key 并复制明文（仅显示一次）。
直接调用 API，或通过 MCP 服务器使用：

curl

bash

curl -X POST https://www.covermagic.site/api/v1/generate \
  -H "Authorization: Bearer cm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "context_prompt": "AI startup founder",
    "overlay_text": "I made $1M",
    "emotion": "shocked",
    "aspect_ratio": "16:9"
  }'

MCP（Claude Desktop、Cursor 等）

json

{
  "mcpServers": {
    "covermagic": {
      "command": "npx",
      "args": ["-y", "covermagic-mcp"],
      "env": {
        "COVERMAGIC_API_KEY": "cm_live_..."
      }
    }
  }
}

认证

所有请求需要在 Authorization header 中携带 API Key。Key 绑定到单个账户，对应的积分余额在网页、REST、MCP 之间共享。

http

Authorization: Bearer cm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Key 在数据库中以 SHA-256 哈希存储，明文仅在创建时返回一次。若 Key 被撤销或泄漏，请在 /account/api-keys 生成新的。

POST /api/v1/generate

生成 3 张封面，每张一个风格（Viral Pop、Cinematic Drama、Luxury Prestige）。消耗 1 积分。返回 Supabase Storage 签名 URL，有效期 7 天。

请求体

字段	类型	必填	描述
context_prompt	string (1–1000)	是	主题 / 场景描述
overlay_text	string (1–200)	是	渲染在封面上的大号粗体标题
emotion	string (1–100)	是	如 shocked、excited、mysterious
aspect_ratio	enum	是	取值之一 `16:9`, `4:3`, `3:4`, `9:16`, `1:1`, `2:3`, `3:2`, `4:5`, `5:4`, `21:9`.
selfie_base64	string	否	可选人脸参考图（PNG/JPG，base64）。不传时生成以物体/场景为主的封面
design_ref_base64	string	否	可选风格/构图参考图
advanced_style	string (≤500)	否	自由格式的风格指令

响应

json

{
  "generation_id": "bf79727b-5c2b-425e-a485-a843adb01c99",
  "credits_remaining": 19,
  "images": [
    {
      "url": "https://...supabase.co/.../viral-pop.png?token=...",
      "style": "Viral Pop",
      "expires_at": "2026-06-11T20:56:42.017Z"
    },
    { "url": "...", "style": "Cinematic Drama", "expires_at": "..." },
    { "url": "...", "style": "Luxury Prestige", "expires_at": "..." }
  ]
}

生成耗时约 20–40 秒，客户端超时建议 ≥120 秒。

MCP 服务器

covermagic-mcp npm 包暴露了一个工具 generate_thumbnail，可在任意兼容 MCP 的客户端中使用。无需手动安装——npx 按需下载。

Claude Desktop / Claude Code

json

{
  "mcpServers": {
    "covermagic": {
      "command": "npx",
      "args": ["-y", "covermagic-mcp"],
      "env": {
        "COVERMAGIC_API_KEY": "cm_live_..."
      }
    }
  }
}

Cursor

json

{
  "mcp.servers": {
    "covermagic": {
      "command": "npx",
      "args": ["-y", "covermagic-mcp"],
      "env": {
        "COVERMAGIC_API_KEY": "cm_live_..."
      }
    }
  }
}

重启客户端后，LLM 会看到 generate_thumbnail 工具。试着对它说"帮我做一张关于 AI 创业的 YouTube 封面，文字写「我做到了 100 万」"，它会返回 3 个图片 URL。

代码示例

Python

python

import os, requests

resp = requests.post(
    "https://www.covermagic.site/api/v1/generate",
    headers={
        "Authorization": f"Bearer {os.environ['COVERMAGIC_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "context_prompt": "AI startup founder hitting 1M revenue",
        "overlay_text": "I made $1M",
        "emotion": "shocked",
        "aspect_ratio": "16:9",
    },
    timeout=180,
)
resp.raise_for_status()
data = resp.json()
for img in data["images"]:
    print(f"{img['style']}: {img['url']}")

Node.js / TypeScript

typescript

const res = await fetch("https://www.covermagic.site/api/v1/generate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.COVERMAGIC_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    context_prompt: "AI startup founder hitting 1M revenue",
    overlay_text: "I made $1M",
    emotion: "shocked",
    aspect_ratio: "16:9",
  }),
});
const data = await res.json();
data.images.forEach((img: { style: string; url: string }) =>
  console.log(`${img.style}: ${img.url}`),
);

错误码

HTTP	含义
400	字段缺失、值越界、枚举非法
401	API Key 缺失 / 无效 / 已撤销
402	积分不足，请在网页购买
403	账户已封禁
429	限流（60 次/分钟/IP），60 秒后重试
503	AI 服务暂时不可用
504	AI 生成超时，可安全重试

生成失败不会扣积分——仅在返回 200 后才扣除。

定价

API / MCP 是按用量计费——每张图 $0.20（每次调用返回 3 张图 = $0.60）。绑定信用卡后无需预付，按实际使用量自动扣费。

套餐	USD	CNY	积分	每次成本
Starter	$3	¥21	5	$0.60
Popular	$10	¥70	20	$0.50
Pro	$20	¥140	45	$0.44

网页用户仍可选 预付积分包（不强制绑卡），价格如下：

查看积分包

常见问题

图片 URL 有效期多久？

从生成时算 7 天。如需长期保存，请在 7 天内把 PNG 下载到自己的存储。

一定要上传自拍照吗？

不需要。selfie_base64 是可选的。不传时生成以物体/场景为主的封面——非常适合只有标题/主题元数据的 agent。

限流是多少？

每 IP 每分钟 60 次。需要更高额度可联系我们。

有沙盒 / 测试环境吗？

暂时没有。注册即送的 3 次免费积分就是你的沙盒。