API roadmap — Nhà phát triển

Tổng quan

Ba cách tích hợp, một nền tảng.

API của Bluweo cho phép ứng dụng bên thứ ba và tác nhân AI truy cập bằng lập trình mọi thứ mà giao diện web của studio làm được — tìm trong thư viện biểu tượng 3D, tạo biến thể mới từ câu lệnh, quản lý lượt tải và lắng nghe các sự kiện chạy nền.

REST API — gọi đồng bộ cho mọi HTTP client.
MCP server — công cụ cắm-là-chạy cho Claude, Cursor và mọi tác nhân hỗ trợ MCP.
Webhooks — đẩy bất đồng bộ cho các lần tạo kéo dài và sự kiện thanh toán.

Lưu ý: Quyền truy cập API thuộc gói Studio. Gói Free và Designer chỉ dùng giao diện web — xem phần Giới hạn tần suất bên dưới.

REST, MCP và webhook — ba cách tích hợp toả ra từ nền tảng Bluweo.

Bắt đầu nhanh

Lần gọi đầu tiên trong chưa đầy 60 giây.

Tạo tài khoản và nâng cấp lên Studio.
Tạo khoá API tại /dashboard/billing → API keys. Khoá bắt đầu bằng blu_live_.
Gửi kèm dưới dạng Bearer token trong mọi yêu cầu.
Gọi GET /v1/icons/search?q=fox để xác nhận khoá hoạt động.

URL gốc: https://api.bluweo.com. Mọi yêu cầu đều phải dùng HTTPS — API sẽ từ chối HTTP thường.

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

Xác thực

Khoá Bearer, theo phạm vi không gian làm việc.

Mọi yêu cầu API đều phải kèm header Authorization: Bearer <key> này. Khoá được cấp từ bảng điều khiển và gắn với một không gian làm việc; cấp độ của khoá quyết định giới hạn tần suất.

Định dạng khoá: blu_live_* (chính thức) hoặc blu_test_* (sandbox — không tính phí, kết quả có hình mờ).
Chỉ hiện một lần: chúng tôi băm khoá ở phía máy chủ. Nếu bạn làm mất, hãy xoay khoá mới.
Xoay khoá: có thể xoay khoá bằng POST /v1/keys/:id/roll; khoá cũ vẫn dùng được thêm 24 giờ để bạn dễ chuyển đổi.
Thu hồi: DELETE /v1/keys/:id có hiệu lực ngay lập tức.

Xác thực bằng khoá API — header Bearer trong mọi lần gọi.

REST API

Tìm kiếm, tạo, tải xuống, quản lý.

Mọi endpoint đều nằm dưới /v1/. Gửi JSON, nhận JSON. Trường đặt theo kiểu snake_case. Dấu thời gian theo ISO-8601 múi giờ UTC.

Phương thức	Đường dẫn	Mục đích
GET	`/v1/icons`	Liệt kê biểu tượng; lọc theo thẻ, phong cách, màu.
GET	`/v1/icons/search`	Tìm toàn văn trong danh mục.
GET	`/v1/icons/:id`	Chi tiết một biểu tượng và các biến thể.
POST	`/v1/icons/generate`	Khởi tạo một lần tạo bằng AI. Trả về 202.
GET	`/v1/generations/:id`	Hỏi trạng thái / kết quả của một lần tạo.
POST	`/v1/icons/:id/variants`	Tạo biến thể phong cách / màu từ một biểu tượng có sẵn.
GET	`/v1/collections`	Liệt kê các bộ sưu tập tuyển chọn.
POST	`/v1/downloads`	Ghi nhận một lượt tải (tốn 1 tín dụng).
GET	`/v1/me`	Thông tin không gian làm việc và số dư tín dụng.
POST	`/v1/keys`	Cấp một khoá API mới.
DELETE	`/v1/keys/:id`	Thu hồi một khoá.

Việc tạo ảnh là bất đồng bộ — lệnh POST trả về 202 kèm mã công việc; việc dựng thật mất 5–30 giây. Đừng chặn chờ, hãy hỏi trạng thái ở /v1/generations/:id hoặc đăng ký nhận generation.completed webhook.

Luồng tạo bất đồng bộ — POST đưa vào hàng đợi, worker xử lý, webhook thông báo.

# 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_..."

Máy chủ MCP

Để tác nhân AI dùng Bluweo như một công cụ.

Model Context Protocol (MCP) là chuẩn mở của Anthropic giúp tác nhân AI gọi được công cụ bên ngoài. Máy chủ của chúng tôi đặt tại /api/mcp (Streamable HTTP) — thêm URL này vào Claude Code, Claude Desktop, Cursor hay bất kỳ client hỗ trợ MCP nào, và tác nhân có thể tìm, xem trước, tải xuống và tạo biểu tượng ngay giữa cuộc trò chuyện. Không cần cài đặt gì.

Máy chủ MCP cung cấp bảy công cụ:

search_icons — tìm theo từ khoá / danh mục / phong cách / bộ sưu tập.
get_icon — chi tiết kèm bản xem trước 128px mà tác nhân nhìn được.
list_collections — duyệt các bộ tuyển chọn.
get_account — gói, tín dụng, hạn mức tải.
download_icon — tệp 512px / bản gốc, tính phí y hệt trên website.
generate_icon — tạo trong Studio từ một câu lệnh.
list_generations — các lần chạy Studio gần đây kèm URL ảnh.

search_icons dùng được không cần khoá (100 lượt mỗi ngày). Mọi công cụ khác đều cần khoá API cá nhân của gói Studio, gửi qua Authorization: Bearer blu_live_… — tạo trong Cài đặt → Khoá API. Đọc hướng dẫn MCP →

Luồng MCP — tác nhân gọi công cụ, máy chủ MCP chuyển sang REST, kết quả quay lại tác nhân.

# 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

Thông báo đẩy cho việc chạy nền.

Cấu hình một URL webhook trong bảng điều khiển. Chúng tôi sẽ POST một payload JSON có chữ ký mỗi khi có việc đáng chú ý — chủ yếu để bạn khỏi phải liên tục hỏi trạng thái tạo ảnh.

Các sự kiện chúng tôi phát:

generation.completed — kết quả đã sẵn sàng để tải.
generation.failed — tín dụng được hoàn tự động; payload có kèm lý do lỗi.
credits.low — số dư của bạn đã xuống dưới 20% hạn mức của gói.
subscription.updated — gói đã đổi / gia hạn / huỷ.

Mọi payload đều kèm header Bluweo-Signature — là mã HMAC-SHA256 của phần thân, tính bằng khoá bí mật webhook của bạn. Luôn xác minh trước khi tin payload; một lệnh POST không chữ ký có thể là yêu cầu giả mạo.

# 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>

Giới hạn tần suất và hạn mức

Theo từng khoá, từng tháng — và theo giây để mọi người đều công bằng.

Mỗi khoá chịu hai giới hạn: lưu lượng hằng tháng (hạn mức theo cấp gói) và đợt tăng ngắn (10 yêu cầu/giây, để bảo vệ tài nguyên dùng chung). Cả hai đều được trả về trong mọi phản hồi qua các header X-RateLimit-* tiêu chuẩn.

Gói	Truy cập API	Hạn mức tháng	Đợt tăng
Free	— (chỉ giao diện web)	—	—
Designer	— (chỉ giao diện web)	—	—
Studio	REST · MCP · Webhooks	10,000 req	10 req/s

Việc tạo ảnh và tải xuống còn tiêu tín dụng trong hạn mức của gói — xem Bảng giá. Việc nạp thêm gói tín dụng không làm tăng hạn mức API; nó chỉ chi trả cho chi phí tạo ảnh.

Vượt giới hạn sẽ nhận 429 Too Many Requests kèm header Retry-After Hãy ngừng gửi trong khoảng thời gian đó rồi thử lại — lùi lại không bị phạt gì cả.

Truy cập API theo cấp gói — Free và Designer chỉ dùng giao diện web; Studio mở khoá 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

Lỗi

Mã HTTP thông dụng + phần thân JSON có cấu trúc.

Các mã trạng thái thường gặp:

Mã	Ý nghĩa
`200`	OK — gọi đồng bộ thành công.
`202`	Accepted — công việc bất đồng bộ đã vào hàng đợi.
`400`	Thân yêu cầu hoặc tham số truy vấn không hợp lệ.
`401`	Thiếu khoá API hoặc khoá không hợp lệ.
`402`	Hết tín dụng — hãy nạp thêm rồi thử lại.
`403`	Khoá hợp lệ nhưng cấp gói không cho phép truy cập API.
`404`	Không tìm thấy tài nguyên.
`409`	Xung đột trạng thái (ví dụ thu hồi một khoá đã thu hồi).
`429`	Chạm giới hạn tần suất — xem `Retry-After`.
`5xx`	Lỗi từ phía chúng tôi. Chúng tôi tự thử lại các yêu cầu idempotent; bạn cũng có thể thử lại an toàn.

Mọi phần thân lỗi đều là JSON: { "error": { "code", "message", "request_id" } }. Khi liên hệ hỗ trợ, hãy gửi kèm request_id để chúng tôi tra được nhật ký.

# 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..."
  }
}

Giới hạn

Những gì API chưa làm được — nói rõ ngay từ đầu.

Không hỗ trợ ngoại tuyến / cài tại chỗ. Việc tạo ảnh luôn chạy trên hạ tầng của chúng tôi. Thư viện biểu tượng có thể lưu đệm ở phía client; còn việc tạo bằng AI thì không.
Không tạo hàng loạt trong một lần gọi. Mỗi POST /v1/icons/generate xử lý một câu lệnh × tối đa 4 kết quả. Với lô lớn hơn, hãy tự chia ra gọi song song; giới hạn đợt tăng vẫn áp dụng.
Độ dài câu lệnh tối đa: 1.000 ký tự. Câu lệnh dài hơn sẽ bị từ chối với mã 400.
Chính sách nội dung. Chúng tôi chặn các câu lệnh nhắm tới người thật, nhân vật có bản quyền, nội dung khiêu dâm hoặc thù ghét. Khi bị chặn, hệ thống trả về 400 kèm code: "policy_violation".
Độ phân giải kết quả tối đa 2048 × 2048. Độ phân giải cao hơn cần hợp đồng riêng.
Thời gian tạo: 5–30 giây. Trường hợp xấu nhất (hàng đợi đầy): tới 2 phút. Hãy thiết kế theo hướng bất đồng bộ — dùng webhook thay vì vòng lặp hỏi liên tục.
Giao thức MCP: chỉ Streamable HTTP. Chưa có gói stdio (npx) chạy cục bộ — hãy kết nối tới URL được lưu trữ sẵn.
Cấp Studio không có SLA. Hợp đồng Enterprise gồm cam kết hoạt động 99,9% và hỗ trợ riêng. Liên hệ với chúng tôi.

Cần thứ gì đó nằm ngoài danh sách này?

Gói Enterprise mở khoá:

Độ phân giải riêng và tinh chỉnh phong cách trên chính tài sản thương hiệu của bạn.
Năng lực xử lý riêng (không dùng chung hàng đợi).
Triển khai VPC / tại chỗ.
Hỗ trợ riêng + SLA 99,9%.
Giá theo lượng khi vượt 10 nghìn yêu cầu / tháng.

Nói chuyện với bộ phận kinh doanh →

Phiên bản

v1 là bản hiện hành. Thay đổi phá vỡ tương thích sẽ ra mắt dưới dạng v2.

Phiên bản nằm trong đường dẫn URL: /v1/.... Trong cùng một phiên bản, chúng tôi chỉ thực hiện thay đổi mang tính bổ sung — trường mới, endpoint mới, loại sự kiện mới. Chúng tôi sẽ không bao giờ bỏ một trường hay đổi kiểu dữ liệu của nó trong cùng một phiên bản.

Khi chúng tôi ra mắt v2, v1 bản cũ vẫn chạy ít nhất 12 tháng kèm ngày ngừng hỗ trợ được công bố qua endpoint changelog và gửi email tới tất cả người dùng API.

Nhật ký thay đổi: GET /v1/changelog trả về mọi thay đổi kể từ khi ra mắt, mới nhất trước.
Trang trạng thái: status.bluweo.com xem tình trạng hoạt động theo thời gian thực và lịch sử sự cố.
Cập nhật qua email: đăng ký từ bảng điều khiển. Chúng tôi chỉ gửi khi báo trước thay đổi phá vỡ tương thích và khi có sự cố lớn.

# 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)"
  ]
}

Sẵn sàng bắt tay vào làm?

Tạo khoá API đầu tiên từ bảng điều khiển, hoặc liên hệ nếu bạn cần một hợp đồng riêng.

Nâng cấp lên Studio Nói chuyện với bộ phận kinh doanh