แผน API — นักพัฒนา

ภาพรวม

สามช่องทางการเชื่อมต่อ หนึ่งแพลตฟอร์ม

Bluweo API ให้แอปบุคคลที่สามและ AI agent เข้าถึงทุกอย่างที่ UI เว็บของสตูดิโอทำได้ผ่านการเขียนโปรแกรม — ค้นหาคลังไอคอน 3D สร้างรูปแบบใหม่จากพรอมต์ จัดการการดาวน์โหลด และรับฟังเหตุการณ์แบบ async

REST API — การเรียกแบบ synchronous สำหรับ HTTP client ใดก็ได้
MCP server — เครื่องมือพร้อมใช้สำหรับ Claude, Cursor และ agent ใดก็ตามที่รองรับ MCP
Webhooks — การ push แบบ async สำหรับงานสร้างที่ใช้เวลานาน + เหตุการณ์การเรียกเก็บเงิน

ข้อควรทราบ: การเข้าถึง API เป็นส่วนหนึ่งของ แพ็กเกจ Studio. แพ็กเกจ Free และ Designer ใช้ได้เฉพาะ UI เว็บ — ดูขีดจำกัดอัตราด้านล่าง

REST, MCP และ webhooks — สามช่องทางการเชื่อมต่อที่แตกออกจากแพลตฟอร์ม Bluweo

เริ่มต้นใช้งาน

การเรียกครั้งแรกของคุณในเวลาไม่ถึง 60 วินาที

สร้างบัญชี แล้วอัปเกรดเป็น Studio
สร้าง API key ที่ /dashboard/billing → API keys. คีย์จะขึ้นต้นด้วย blu_live_.
ส่งคีย์เป็น Bearer token ไปกับทุกคำขอ
ลองเรียก GET /v1/icons/search?q=fox เพื่อยืนยันว่าคีย์ใช้งานได้

Base 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_* (sandbox — ไม่คิดค่าใช้จ่าย ผลลัพธ์มีลายน้ำ).
แสดงครั้งเดียว: เรา hash คีย์ไว้ฝั่งเซิร์ฟเวอร์ หากคุณทำคีย์หาย ให้หมุนคีย์ใหม่
การหมุนคีย์: หมุนคีย์ใหม่ได้ด้วย POST /v1/keys/:id/roll; คีย์เดิมจะยังใช้ได้อีก 24 ชั่วโมงเพื่อให้ย้ายระบบได้ราบรื่น
การเพิกถอน: DELETE /v1/keys/:id มีผลทันที

การยืนยันตัวตนด้วย API key — เฮดเดอร์ Bearer ในทุกการเรียก

REST API

ค้นหา สร้าง ดาวน์โหลด จัดการ

ทุก endpoint อยู่ภายใต้ /v1/. รับ JSON ส่งกลับ JSON ฟิลด์เป็น snake-case และ timestamp แบบ ISO-8601 ในโซน UTC

เมธอด	เส้นทาง	วัตถุประสงค์
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 key ใหม่
DELETE	`/v1/keys/:id`	เพิกถอนคีย์

งานสร้างเป็นแบบ async — POST จะคืนค่า 202 พร้อม job id ส่วนการเรนเดอร์จริงใช้เวลา 5–30 วินาที ให้ poll ที่ /v1/generations/:id หรือสมัครรับ generation.completed webhooks แทนการรอแบบ blocking

ขั้นตอนการสร้างแบบ async — POST เข้าคิว worker ประมวลผล 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 server

ให้ AI agent ใช้ Bluweo เป็นเครื่องมือ

โปรโตคอล Model Context Protocol (MCP) คือมาตรฐานเปิดของ Anthropic ที่ให้ AI agent เรียกใช้เครื่องมือภายนอกได้ server ของเราอยู่ที่ /api/mcp (Streamable HTTP) — เพิ่ม URL นี้ใน Claude Code, Claude Desktop, Cursor หรือไคลเอนต์ใดก็ตามที่รองรับ MCP แล้ว agent ก็ค้นหา ดูตัวอย่าง ดาวน์โหลด และสร้างไอคอนได้ระหว่างสนทนา ไม่ต้องติดตั้งอะไร

MCP server เปิดให้ใช้เครื่องมือเจ็ดตัว:

search_icons — ค้นหาด้วยคำค้น / หมวดหมู่ / สไตล์ / collection
get_icon — รายละเอียดพร้อมรูปตัวอย่าง 128px ที่ agent มองเห็นได้
list_collections — เรียกดูชุดไอคอนที่คัดสรร
get_account — แพลน เครดิต และเพดานขนาดดาวน์โหลด
download_icon — ไฟล์ 512px / ต้นฉบับ คิดเครดิตเหมือนบนเว็บทุกประการ
generate_icon — สร้างไอคอนใหม่ด้วย Studio จาก prompt
list_generations — รายการที่สร้างด้วย Studio ล่าสุด พร้อม URL รูป

search_icons ใช้ได้โดยไม่ต้องมี key (100 ครั้ง/วัน) ส่วนเครื่องมืออื่นต้องใช้ API key ส่วนตัวของแพลน Studio ส่งมาเป็น Authorization: Bearer blu_live_… — สร้างได้ที่ Settings → API keys อ่านคู่มือ MCP →

ขั้นตอน MCP — agent เรียกเครื่องมือ MCP server แปลงเป็น REST ผลลัพธ์ส่งกลับไปยัง agent

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

Webhooks

การแจ้งเตือนแบบ push สำหรับงาน async

ตั้งค่า URL ของ webhook ในแดชบอร์ดของคุณ เราจะ POST เพย์โหลด JSON ที่เซ็นลายเซ็นทุกครั้งที่มีเหตุการณ์สำคัญเกิดขึ้น — โดยหลักเพื่อให้คุณไม่ต้องคอยตรวจสอบสถานะการสร้างเอง

เหตุการณ์ที่เราส่ง:

generation.completed — ผลลัพธ์พร้อมให้ดาวน์โหลดแล้ว
generation.failed — คืนเครดิตอัตโนมัติ เพย์โหลดจะระบุสาเหตุของข้อผิดพลาด
credits.low — ยอดคงเหลือของคุณต่ำกว่า 20% ของโควต้าในแพ็กเกจ
subscription.updated — แพ็กเกจถูกเปลี่ยน / ต่ออายุ / ยกเลิก

ทุกเพย์โหลดจะมีเฮดเดอร์ Bluweo-Signature — ค่า HMAC-SHA256 ของเนื้อหาที่คำนวณด้วย webhook secret ของคุณ ตรวจสอบลายเซ็นทุกครั้งก่อนเชื่อถือเพย์โหลด; เพราะ 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 req/s เพื่อปกป้องทรัพยากรที่ใช้ร่วมกัน) ทั้งสองค่าจะถูกส่งกลับในทุก response ผ่านเฮดเดอร์ X-RateLimit-* มาตรฐาน

แพ็กเกจ	การเข้าถึง API	โควต้ารายเดือน	เบิร์สต์
Free	— (เฉพาะ UI เว็บ)	—	—
Designer	— (เฉพาะ UI เว็บ)	—	—
Studio	REST · MCP · Webhooks	10,000 req	10 req/s

การสร้างและการดาวน์โหลด ยัง ใช้เครดิตจากโควต้าของแพ็กเกจด้วย — ดู ราคา. การเติมแพ็กเครดิตไม่ได้เพิ่มโควต้า API แต่ใช้จ่ายเป็นค่าการสร้างเท่านั้น

เมื่อเกินขีดจำกัดจะได้รับ 429 Too Many Requests พร้อมเฮดเดอร์ Retry-After ให้หยุดส่งทราฟฟิกตามเวลาที่ระบุแล้วลองใหม่ — ไม่มีบทลงโทษหากคุณชะลอการเรียก

การเข้าถึง API ตามระดับแพ็กเกจ — Free และ Designer ใช้ได้เฉพาะ UI เว็บ; 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 — สำเร็จแบบ synchronous
`202`	Accepted — งาน async เข้าคิวแล้ว
`400`	เนื้อหาคำขอหรือ query param ไม่ถูกต้อง
`401`	ไม่มี API key หรือคีย์ไม่ถูกต้อง
`402`	เครดิตหมด — เติมเครดิตแล้วลองใหม่
`403`	คีย์ถูกต้อง แต่ระดับแพ็กเกจไม่ให้สิทธิ์เข้าถึง API
`404`	ไม่พบทรัพยากร
`409`	สถานะขัดแย้งกัน (เช่น เพิกถอนคีย์ที่ถูกเพิกถอนไปแล้ว)
`429`	ชนขีดจำกัดอัตรา — ดู `Retry-After`.
`5xx`	เป็นปัญหาฝั่งเรา ระบบจะลองใหม่ให้อัตโนมัติสำหรับคำขอแบบ idempotent และคุณลองใหม่เองได้อย่างปลอดภัย

เนื้อหาข้อผิดพลาดทุกรายการเป็น JSON: { "error": { "code", "message", "request_id" } }. โปรดแนบ request_id เมื่อติดต่อฝ่ายสนับสนุน — เราจะดึง trace ให้ได้

# 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 ทำไม่ได้ในวันนี้ — กำหนดความคาดหวังไว้ล่วงหน้า

ไม่รองรับ offline / on-prem งานสร้างทำงานบนโครงสร้างพื้นฐานของเราเสมอ คลังไอคอนแคชไว้ฝั่งไคลเอนต์ได้ แต่การสร้างด้วย AI ทำไม่ได้
สร้างเป็นชุดในการเรียกครั้งเดียวไม่ได้ แต่ละ POST /v1/icons/generate รองรับหนึ่งพรอมต์ × ไม่เกิน 4 ผลลัพธ์ หากต้องการชุดใหญ่กว่านี้ให้กระจายการเรียกเอง โดยขีดจำกัดเบิร์สต์ยังมีผลอยู่
ความยาวพรอมต์สูงสุด: 1,000 ตัวอักษร พรอมต์ที่ยาวกว่านี้จะถูกปฏิเสธด้วย 400
นโยบายเนื้อหา เราบล็อกพรอมต์ที่ขอภาพบุคคลจริง ตัวละครที่มีลิขสิทธิ์ เนื้อหา NSFW หรือเนื้อหาที่สร้างความเกลียดชัง กรณีที่ไม่ผ่านจะคืนค่า 400 พร้อม code: "policy_violation".
ความละเอียดผลลัพธ์สูงสุด 2048 × 2048 ความละเอียดที่สูงกว่านี้ต้องทำสัญญาแบบกำหนดเอง
เวลาในการสร้าง: 5–30 วินาที กรณีแย่ที่สุด (คิวเต็ม): นานถึง 2 นาที ควรออกแบบให้เป็น async — ใช้ webhooks แทนการ poll ถี่ๆ
transport ของ MCP: Streamable HTTP เท่านั้น ยังไม่มีแพ็กเกจ stdio (npx) สำหรับรันในเครื่อง — ให้เชื่อมต่อผ่าน URL ที่เราโฮสต์
ไม่มี SLA ในระดับ Studio สัญญาแบบ Enterprise รวม uptime 99.9% + การสนับสนุนเฉพาะ ติดต่อเรา.

ต้องการสิ่งที่รายการนี้ให้คุณไม่ได้?

แพ็กเกจ Enterprise ปลดล็อก:

ความละเอียดที่กำหนดเอง + การปรับแต่งสไตล์บนแอเซตแบรนด์ของคุณเอง
ความจุเฉพาะ (ไม่มีคิวร่วม)
การติดตั้งแบบ VPC / on-prem
การสนับสนุนเฉพาะ + SLA 99.9%
ราคาตามปริมาณเกิน 10k req / เดือน

ติดต่อฝ่ายขาย →

การกำหนดเวอร์ชัน

v1 คือเวอร์ชันปัจจุบัน การเปลี่ยนแปลงที่กระทบการใช้งานเดิมจะออกเป็น v2.

เวอร์ชันอยู่ในพาธของ URL: /v1/.... ภายในเวอร์ชันเดียวกัน เราจะทำเฉพาะการเปลี่ยนแปลงแบบ เพิ่มเติม เท่านั้น — ฟิลด์ใหม่ endpoint ใหม่ และประเภทเหตุการณ์ใหม่ เราจะไม่ลบฟิลด์หรือเปลี่ยนชนิดข้อมูลภายในเวอร์ชันเดียวกัน

เมื่อเราปล่อย v2, v1 จะยังใช้งานได้ต่ออีกอย่างน้อย 12 เดือน โดยจะประกาศวันเลิกใช้ผ่าน endpoint changelog และส่งอีเมลถึงผู้ใช้ API ทุกคน

Changelog: GET /v1/changelog คืนค่าการเปลี่ยนแปลงทั้งหมดตั้งแต่เปิดตัว เรียงจากใหม่สุด
หน้าสถานะ: status.bluweo.com สำหรับดู uptime แบบเรียลไทม์ + ประวัติเหตุขัดข้อง
อัปเดตทางอีเมล: สมัครรับได้จากแดชบอร์ด เราส่งเฉพาะการแจ้งเตือนการเปลี่ยนแปลงที่กระทบการใช้งาน + เหตุขัดข้องสำคัญ

# 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 key แรกของคุณจากแดชบอร์ด หรือติดต่อเราหากคุณต้องการสัญญาแบบกำหนดเอง

อัปเกรดเป็น Studio ติดต่อฝ่ายขาย