API roadmap — 开发者 — Realistic Icon

概览

三种接入方式，一个平台。

Bluweo API 让第三方应用和 AI 智能体能够以编程方式使用工作室网页端的全部能力 — 搜索 3D 图标库、根据提示词生成新的变体、管理下载，以及订阅异步事件。

REST API — 面向任意 HTTP 客户端的同步调用。
MCP server — 可直接接入 Claude、Cursor 以及任何支持 MCP 的智能体的工具。
Webhooks — 针对长时间生成任务与计费事件的异步推送。

请注意： API 访问属于 Studio 方案. Free 和 Designer 方案只能使用网页端 — 详见下方的速率限制。

REST、MCP 与 Webhook — 从 Bluweo 平台延伸出的三种接入方式。

快速开始

60 秒内完成第一次调用。

创建账号并升级到 Studio。
在此生成 API 密钥： /dashboard/billing → API keys. 密钥以此开头： blu_live_.
在每个请求中作为 Bearer 令牌发送。
调用 GET /v1/icons/search?q=fox 确认密钥可用。

基础 URL： https://api.bluweo.com. 所有请求都必须使用 HTTPS — API 会拒绝明文 HTTP。

# 1. Search the icon catalogue
curl https://api.bluweo.com/v1/icons/search?q=fox \
  -H "Authorization: Bearer blu_live_..."

身份认证

Bearer 密钥，按工作区隔离。

每个 API 请求都必须包含 Authorization: Bearer <key> 请求头。密钥在你的控制台中签发，并绑定到一个工作区；速率限制由密钥所属的层级决定。

密钥格式： blu_live_* (生产环境) 或 blu_test_* (沙盒 — 不计费，输出带水印).
只显示一次： 我们在服务端对密钥做哈希处理。如果丢失，请轮换一把新的。
轮换： 可以用它来轮换密钥： POST /v1/keys/:id/roll; 为便于迁移，旧密钥会继续有效 24 小时。
吊销： DELETE /v1/keys/:id 立即生效。

REST API

搜索、生成、下载、管理。

所有端点都位于 /v1/. 请求和响应都是 JSON。字段使用蛇形命名，时间戳为 UTC 的 ISO-8601 格式。

方法	路径	用途
GET	`/v1/icons`	列出图标；可按标签、风格、颜色筛选。
GET	`/v1/icons/search`	对目录做全文搜索。
GET	`/v1/icons/:id`	单个图标的详情及其变体。
POST	`/v1/icons/generate`	发起一次 AI 生成。返回 202。
GET	`/v1/generations/:id`	轮询某次生成的状态／输出。
POST	`/v1/icons/:id/variants`	基于已有图标派生风格／颜色变体。
GET	`/v1/collections`	列出精选合集。
POST	`/v1/downloads`	记录一次下载（消耗 1 积分）。
GET	`/v1/me`	工作区信息与积分余额。
POST	`/v1/keys`	签发一把新的 API 密钥。
DELETE	`/v1/keys/:id`	吊销一把密钥。

生成任务是 异步的 — POST 会返回 202 和一个任务 ID，实际渲染需要 5–30 秒。请不要阻塞等待，改为轮询 /v1/generations/:id 或订阅 generation.completed Webhook。

# Generate a 3D icon
curl https://api.bluweo.com/v1/icons/generate \
  -X POST \
  -H "Authorization: Bearer blu_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "cute 3D fox character, studio lighting",
    "kind": "icon",
    "aspect": "1:1",
    "outputs": 4
  }'

# → 202 { "id": "gen_01H...", "status": "queued" }

# Poll until done
curl https://api.bluweo.com/v1/generations/gen_01H... \
  -H "Authorization: Bearer blu_live_..."

MCP 服务器

让 AI 智能体把 Bluweo 当作工具使用。

Model Context Protocol （MCP）是 Anthropic 推出的开放标准，让 AI 智能体可以调用外部工具。我们的服务器部署在 /api/mcp （Streamable HTTP）。把这个 URL 添加到 Claude Code、Claude Desktop、Cursor 或任何支持 MCP 的客户端，智能体就能在对话中搜索、预览、下载和生成图标。无需安装任何东西。

MCP 服务器提供七个工具：

search_icons — 按关键词／分类／风格／合集搜索。
get_icon — 详情，以及一张智能体可以看到的 128px 预览图。
list_collections — 浏览精选合集。
get_account — 方案、积分、下载上限。
download_icon — 512px／原始文件，计费方式与网站完全一致。
generate_icon — 根据提示词在工作室生成。
list_generations — 最近的工作室运行记录及其图片 URL。

search_icons 无需密钥即可使用（每天 100 次）。其他工具都需要 Studio 方案的个人 API 密钥，作为 Authorization: Bearer blu_live_… — 在「设置 → API 密钥」中创建。阅读 MCP 指南 →

MCP 流程 — 智能体调用工具，MCP 服务器转换为 REST，结果返回给智能体。

# Claude Code — the Studio-plan key is required
claude mcp add --transport http realisticicon \
  https://realisticicon.com/api/mcp \
  --header "Authorization: Bearer blu_live_..."

Webhook

异步任务的推送通知。

在控制台里配置一个 Webhook URL。每当有值得关注的事情发生，我们就会 POST 一份带签名的 JSON — 主要是为了让你不必轮询生成状态。

我们会发出的事件：

generation.completed — 输出已可下载。
generation.failed — 积分自动退回；载荷中包含失败原因。
credits.low — 你的余额已低于方案额度的 20%。
subscription.updated — 方案已变更／续费／取消。

每份载荷都包含一个 Bluweo-Signature 请求头 — 使用你的 Webhook 密钥对请求体做 HMAC-SHA256 计算得出。 信任载荷之前请务必验证; 未签名的 POST 可能是伪造请求。

# Example payload Bluweo POSTs to your endpoint
{
  "event": "generation.completed",
  "data": {
    "id": "gen_01H...",
    "status": "done",
    "outputs": [
      { "url": "https://cdn.bluweo.com/g/.../0.png", "width": 1024, "height": 1024 }
    ],
    "credits_used": 5
  },
  "created_at": "2026-05-16T17:42:11Z"
}

# Header attached:
# Bluweo-Signature: t=1715882531,v1=<hmac>

速率限制与配额

按密钥、按月计算 — 同时也按秒限制，以保证公平。

每把密钥都受两种限制： 月度用量 （按方案层级的配额）和 短时突发 （10 次／秒，用于保护共享资源）。两者都会在每次响应中通过标准的 X-RateLimit-* 请求头返回。

方案	API 访问	月度配额	突发
Free	—（仅网页端）	—	—
Designer	—（仅网页端）	—	—
Studio	REST · MCP · Webhooks	10,000 req	10 req/s

生成和下载还会消耗方案额度中的积分 — 详见价格. 购买积分包不会提高 API 配额，它只用来支付生成本身的开销。

超出限制会返回 429 Too Many Requests 并带上 Retry-After 请求头。暂停发送请求相应时长后再重试即可 — 主动退避不会有额外惩罚。

按方案层级的 API 访问 — Free 与 Designer 只能用网页端，Studio 解锁 API。

# Every response includes:
X-RateLimit-Limit:        10000
X-RateLimit-Remaining:    9847
X-RateLimit-Reset:        1715958000   # unix epoch
X-RateLimit-Burst-Limit:  10
X-RateLimit-Burst-Remaining: 7

# On 429:
Retry-After: 3            # seconds

错误

常规 HTTP 状态码 + 结构化的 JSON 响应体。

常见状态码：

状态码	含义
`200`	OK — 同步调用成功。
`202`	Accepted — 异步任务已入队。
`400`	请求体或查询参数无效。
`401`	缺少或无效的 API 密钥。
`402`	积分不足 — 充值后重试。
`403`	密钥有效，但当前方案层级不包含 API 访问权限。
`404`	找不到资源。
`409`	状态冲突（例如吊销一把已被吊销的密钥）。
`429`	触发速率限制 — 详见 `Retry-After`.
`5xx`	我们这边的问题。幂等请求会自动重试；你自己重试也是安全的。

所有错误响应体都是 JSON： { "error": { "code", "message", "request_id" } }. 联系支持时请附上 request_id 我们可以据此调取调用链路。

# 402 — out of credits
{
  "error": {
    "code": "insufficient_credits",
    "message": "Account has 3 credits; generate(outputs=4) requires 20.",
    "request_id": "req_01H9R..."
  }
}

# 429 — rate limit
{
  "error": {
    "code": "rate_limited",
    "message": "Burst limit of 10 req/s exceeded.",
    "request_id": "req_01H9R..."
  }
}

限制

API 目前做不到的事 — 先说清楚，免得期待落空。

不支持离线／私有化部署。 生成始终在我们的基础设施上运行。图标库可以在客户端缓存，但 AI 生成不行。
单次调用不支持批量生成。 每次 POST /v1/icons/generate 只处理一条提示词 × 最多 4 张输出。更大的批量请自行并发；突发限制依然适用。
提示词最长 1,000 个字符。 超长的提示词会以 400 拒绝。
内容政策。 我们会拦截涉及真实人物、受版权保护的角色、成人内容或仇恨内容的提示词。被拦截时返回 400 并附带 code: "policy_violation".
输出分辨率上限为 2048 × 2048。 更高的分辨率需要单独签订合同。
生成耗时：5–30 秒。 最坏情况（队列饱和）可能长达 2 分钟。请按异步来设计 — 使用 Webhook，而不是高频轮询。
MCP 传输：仅 Streamable HTTP。 暂无本地 stdio（npx）包 —— 请连接托管的 URL。
Studio 层级不提供 SLA。 企业版合同包含 99.9% 可用性与专属支持。联系我们.

还需要这份清单之外的能力？

企业版方案可解锁：

自定义分辨率，以及基于你自有品牌素材的风格微调。
专属算力（不与他人共享队列）。
VPC／私有化部署。
专属支持 + 99.9% SLA。
月请求量超过 1 万次的批量定价。

联系销售 →

版本管理

v1 为当前版本。破坏性变更会以此发布： v2.

版本号写在 URL 路径中： /v1/.... 在同一个版本内，我们只做 增量式 变更 — 新增字段、新增端点、新增事件类型。我们绝不会在同一版本内删除字段或更改其类型。

当我们发布 v2, v1 时，旧版本至少还会继续运行 12 个月 废弃日期会通过以下端点公布： changelog 并通过邮件通知所有 API 用户。

变更日志： GET /v1/changelog 返回自上线以来的所有变更，最新的排在前面。
状态页： status.bluweo.com 可查看实时可用性与故障历史。
邮件通知： 在控制台中订阅。我们只会为破坏性变更预告和重大故障发送邮件。

# Read the changelog (no auth needed)
curl https://api.bluweo.com/v1/changelog | jq

# Sample entry:
{
  "version": "1.4.0",
  "released_at": "2026-04-22",
  "title": "MCP tools: list_collections + variant generation",
  "highlights": [
    "New MCP tool: list_collections",
    "Variant generation now supports color hex shorthand",
    "Webhook signatures use t=...,v1=... format (v0 deprecated 2026-10-22)"
  ]
}

准备好开始了吗？

在控制台生成你的第一把 API 密钥，或者在需要定制合同时联系我们。

升级到 Studio 联系销售