นักพัฒนา

3D Icon API และ MCP Server สำหรับ Claude, Cursor และ AI Agent

ใช้ได้สองทาง MCP server ให้ผู้ช่วย AI ค้นหาไอคอน ดูรูป ดาวน์โหลดไฟล์ และสร้างไอคอนใหม่ได้ในบทสนทนา ส่วน REST API ให้โค้ดของคุณค้นหาและดาวน์โหลดได้แบบเดียวกัน ทั้งสองทางใช้ API key ตัวเดียวกัน และคิดเครดิตแบบเดียวกับบนเว็บทุกประการ

MCP server ทำอะไรได้บ้าง

MCP (Model Context Protocol) คือมาตรฐานเปิดที่แอป AI ใช้เรียกเครื่องมือภายนอก

พอเชื่อมต่อแล้ว ผู้ช่วย AI จะตัดสินใจเองว่าเมื่อไรควรเรียกเครื่องมือของเรา ลองบอกว่า “ขอไอคอน 3D หมาจิ้งจอกน่ารักๆ ทำไอคอนแอป” มันจะค้นหาในคลัง โชว์ตัวอย่างให้ดู แล้วส่งลิงก์ดาวน์โหลดหรือสร้างแบบใหม่ให้ได้ โดยไม่ต้องเปิดเว็บเลย

  • ค้นหาไอคอนกว่า 12,000 ชิ้น ด้วยคำค้น หมวดหมู่ สไตล์ (realistic / isometric / clay) หรือ collection ที่คัดไว้
  • มองเห็นไอคอนจริง: get_icon แนบรูปตัวอย่างไปด้วย ผู้ช่วยที่รองรับรูปภาพจะประเมินให้ได้
  • ดาวน์โหลดไฟล์ 512px หรือต้นฉบับ และสร้างไอคอนใหม่ด้วย Studio โดยคิดเครดิตแบบเดียวกับบนเว็บทุกประการ

ทุก tool เป็นของแพลน Studio ทั้งค้นหา ดูรายละเอียด ดาวน์โหลด 512px/ต้นฉบับ สร้างไอคอน และดูข้อมูลบัญชี ต้องใช้ API key ส่วนตัวของบัญชี Studio (Settings → API keys) ถ้าไม่มีคีย์ หรือใช้คีย์ของแพลน Free/Designer จะเชื่อมต่อและเห็นรายชื่อ tool ได้ แต่เรียกใช้ไม่ได้ทุกตัว ส่วนบนเว็บยังเข้าดูและค้นหาไอคอนได้ฟรีเหมือนเดิม

Endpoint

URL เดียว ใช้ Streamable HTTP ไม่มี session ค้าง

client ที่รองรับ MCP ทุกตัวจะถาม URL ของ server ของเราคือ:

เปิด URL นี้ในเบราว์เซอร์จะเห็นการ์ด JSON บอกรายชื่อ tools ส่วน client จะคุยกับมันด้วย JSON-RPC ผ่าน POST เอง คุณไม่ต้องเรียกเองเลย

https://realisticicon.com/api/mcp

เชื่อมต่อ client

สามขั้น ใช้เวลาประมาณหนึ่งนาที

  1. ถ้าอยู่บนแพลน Studio ให้สร้าง API key ที่ Settings → API keys แล้วคัดลอกไว้ (แสดงครั้งเดียว)
  2. เพิ่ม server ใน client ด้วย URL ด้านล่าง พร้อม header Authorization
  3. สั่งผู้ช่วย AI ให้หาไอคอน มันจะค้นพบ tools เองอัตโนมัติ

ทดสอบ: ถามว่า “มี tool อะไรจาก realisticicon บ้าง” ผู้ช่วยควรตอบรายชื่อ search_icons, get_icon และตัวอื่นๆ

# the key is required — MCP is part of the Studio plan
claude mcp add --transport http realisticicon https://realisticicon.com/api/mcp \
  --header "Authorization: Bearer blu_live_YOUR_KEY"

รันครั้งเดียวใน terminal ใส่ `--scope user` ถ้าอยากใช้ได้ทุกโปรเจกต์ เช็คสถานะด้วย `claude mcp list`

API key

คีย์ผูก server เข้ากับบัญชี Studio และเครดิตของคุณ

  1. เข้าสู่ระบบแล้วเปิด Settings → API keys
  2. กด Create key ตั้งชื่อ (เช่น “Claude Code”, “Cursor”) แล้วคัดลอกคีย์ คีย์ขึ้นต้นด้วย blu_live_ และแสดงเพียงครั้งเดียว
  3. ส่งเป็น header Authorization: Bearer blu_live_… ตอนเพิ่ม server
  4. หมุนเวียนหรือเพิกถอนได้จากหน้าเดิมทุกเมื่อ คีย์เก่าจะหยุดทำงานทันที
เปิด Settings → API keys
เก็บเป็นความลับ
  • คีย์ใช้เครดิตของคุณได้ (ดาวน์โหลด, สร้างไอคอน) ดูแลเหมือนรหัสผ่าน
  • คีย์แก้ไขบัญชี ซื้อเครดิต หรือสร้างคีย์เพิ่มไม่ได้ สิ่งเหล่านั้นต้องล็อกอินผ่านเบราว์เซอร์
  • มีคีย์ที่ใช้งานได้สูงสุด 10 ตัว แนะนำแยกคีย์ต่อเครื่องมือ จะได้เพิกถอนทีละตัวได้

Tools

สิ่งที่ผู้ช่วย AI เรียกได้ ทุก tool ตอบกลับทั้งข้อความอ่านง่ายและข้อมูลแบบมีโครงสร้าง

Toolต้องใช้ทำอะไรลองพูดว่า
search_iconsAPI keyค้นหาไอคอนด้วยคำค้น หมวดหมู่ สไตล์ ชนิด (image / video) หรือ collection ได้ผลลัพธ์ทีละหน้า พร้อม URL ตัวอย่าง 256px และลิงก์หน้าไอคอน“หาไอคอน 3D แก้วกาแฟ สไตล์ clay ให้หน่อย”
get_iconAPI keyรายละเอียดเต็มของไอคอนหนึ่งชิ้น คำอธิบาย แท็ก prompt ที่ใช้สร้าง ขนาดที่มี พร้อมรูป 128px ให้ผู้ช่วยมองเห็น“ขอดูอันที่สอง แล้วบอกว่ามีขนาดอะไรบ้าง”
list_collectionsAPI keyรายชื่อ collection ที่คัดไว้ (Christmas, Marketing essentials, …) เอาไปใส่ search_icons เพื่อไล่ดูได้“มี collection ตามธีมอะไรบ้าง”
get_accountAPI keyแพลน ยอดเครดิต ขนาดดาวน์โหลดสูงสุด และรวมการสร้างด้วย Studio หรือไม่“เหลือเครดิตเท่าไร”
download_iconAPI keyURL ไฟล์ตรงที่ 256px (ฟรี), 512px หรือ PNG ต้นฉบับ หักเครดิตครั้งแรกที่ดาวน์โหลดไอคอนนั้นแบบความละเอียดสูง ดาวน์โหลดซ้ำฟรี“ดาวน์โหลดหมาจิ้งจอกตัวนั้นที่ 512px”
generate_iconAPI keyสร้างไอคอนใหม่ 1–4 รูปจาก prompt ด้วย Studio ใช้ไอคอนในคลังเป็นตัวอ้างอิงสไตล์ได้ ได้ URL รูปและ prompt ที่ขยายแล้ว (ปกติใช้เวลา 1–2 นาที)“สร้างไอคอน 3D แพนด้าแดงถือแก้วกาแฟ”
list_generationsAPI keyรายการที่คุณสร้างด้วย Studio ล่าสุด พร้อม URL รูปและ prompt ผู้ช่วยจะได้หยิบของเดิมมาใช้แทนการเสียเครดิตสร้างซ้ำ“ขอดูไอคอนที่ฉันสร้างไว้ครั้งก่อน”

เครดิตและแพลน

กติกาเดียวกับบนเว็บ เพราะ MCP server เรียกโค้ดคิดเงินชุดเดียวกัน

  • 256px หรือเล็กกว่า: ไม่หักเครดิต แต่ก็ยังต้องเรียกด้วยคีย์เหมือน tool อื่น
  • 512px และต้นฉบับ: 1 เครดิตในครั้งแรกที่ดาวน์โหลดไอคอนนั้น ดาวน์โหลดไอคอนเดิมซ้ำขนาดใดก็ฟรี แพลน Studio ดาวน์โหลดไอคอนใหม่ได้สูงสุดวันละ 60 ชิ้น
  • การสร้างด้วย Studio: คิดต่อรูปตามอัตราของ Studio กันเครดิตไว้ก่อนรัน และคืนให้สำหรับรูปที่สร้างไม่สำเร็จ
  • ถ้าเครดิตหมด tool จะบอกผู้ช่วย AI ให้พาคุณไปหน้า Billing แทนที่จะลองซ้ำ
  • คีย์ของแพลน Free หรือ Designer เห็นรายชื่อ tool ได้แต่เรียกใช้ไม่ได้ เหมือนไม่มีคีย์ ทุก tool ต้องเป็นบัญชี Studio อัปเกรดแล้วคีย์เดิมใช้ได้ทันที
  • 3D เป็นฟีเจอร์เบต้าของแพลน Studio: generate_icon ที่ kind เป็น "3d" จะถูกปฏิเสธในแพลนอื่น
ดูราคา →
เพดานตามแพลน
แพลนขนาดดาวน์โหลดสูงสุดสร้างด้วย Studio
Studio1024pxรวมอยู่ในแพลน

ตัวอย่างคำสั่ง

คำสั่งที่ใช้ได้ดีเมื่อเชื่อมต่อ server แล้ว

  • “อยากได้ไอคอนแอปติดตามนิสัย ขอดูตัวเลือก 3D แบบ realistic 6 แบบ”
    search_icons → เห็นตัวอย่างในแชท → สั่งต่อว่า “อันที่สาม แต่เป็นสไตล์ isometric” เพื่อปรับ
  • “สามอันนี้ อันไหนเข้ากับพื้นหลังสีกรมท่าที่สุด”
    get_icon ทีละอัน → ผู้ช่วยดูรูปจริงก่อนตอบ
  • “ขอไฟล์ต้นฉบับของไอคอนหมาจิ้งจอกอาร์กติก”
    get_account (เช็คแพลน) → download_icon size=original → ได้ URL ไว้บันทึก
  • “ทำไอคอน 3D จรวดสไตล์ clay ให้เหมือนสไตล์ของไอคอน cute-shiba-inu-icon”
    generate_icon พร้อม referenceIconIds → ได้ PNG ใหม่ และบันทึกในประวัติ Studio ด้วย

ข้อจำกัด

เหลือเฟือสำหรับคนใช้จริง แต่รัดกุมสำหรับ loop ที่หลุด

  • เรียก tool ได้ 300 ครั้งต่อเดือน ตามที่การ์ด Studio เขียนไว้ — get_account บอกว่าเหลือเท่าไรและรีเซ็ตเมื่อไร ทุกการเรียก tool นับ รวม search_icons ด้วย ส่วนการเชื่อมต่อ ดูรายชื่อ tool และตัว get_account เองไม่นับ
  • 300 คำขอต่อนาทีต่อคีย์ (คำขอที่ไม่มีคีย์ไปไม่ถึง tool อยู่แล้ว) เกินจากนั้นจะได้ 429 พร้อม Retry-After
  • ค้นหาได้สูงสุด 50 ไอคอนต่อหน้า ไล่หน้าต่อด้วย page และ seed ที่ tool ส่งกลับมา
  • generate_icon ทำงานแบบรอผล อาจใช้เวลาถึงสองสามนาที และจำกัด count ไม่เกิน 4 รูปต่อครั้ง
  • รูปตัวอย่างที่แนบในผลลัพธ์ถูกย่อเหลือ 256px เพื่อให้บทสนทนาเบา

แก้ปัญหา

ข้อความที่ผู้ช่วย AI จะบอก และสิ่งที่ควรทำ

เจอข้อความทำแบบนี้
401 “`get_icon` is part of the Studio plan and needs an API key”เชื่อมต่อโดยไม่มีคีย์ จึงเห็นรายชื่อ tool ได้แต่เรียกใช้ไม่ได้ สร้างคีย์จากบัญชีแพลน Studio ที่ Settings → API keys แล้วเพิ่ม header Authorization จากนั้นเชื่อมต่อใหม่
“The API key was rejected (invalid_api_key / api_key_revoked)”พิมพ์ผิด หรือคีย์ถูกหมุนเวียน/เพิกถอนแล้ว คัดลอกคีย์ปัจจุบันจาก Settings หรือสร้างใหม่
“Not enough credits”เติมเครดิตหรืออัปเกรดที่หน้า Billing ดาวน์โหลด 256px ยังใช้ได้ฟรี
403 “`download_icon` is included in the Studio plan only”คีย์ใช้ได้ แต่บัญชีอยู่บนแพลน Free หรือ Designer ซึ่งไม่มีสิทธิ์ใช้ MCP อัปเกรดเป็น Studio ที่หน้า Billing แล้วคีย์เดิมจะใช้ได้ทันที
client บอกว่าติดต่อ server ไม่ได้เช็คว่า URL ลงท้ายด้วย /api/mcp และใช้ https เปิดในเบราว์เซอร์ควรเห็นการ์ด JSON
429 rate_limitedรอตามวินาทีใน Retry-After แล้วลดความถี่ของระบบอัตโนมัติลง โควตา 300/นาที คิดต่อคีย์
429 monthly_limit_reachedบัญชีใช้โควตา 300 ครั้งของเดือนนี้หมดแล้ว เริ่มใหม่วันที่ 1 ของเดือนถัดไป ระหว่างนี้ get_account ยังเรียกได้ และบอกเวลารีเซ็ตที่แน่นอน

REST API

คลังไอคอนและการคิดเครดิตชุดเดียวกัน สำหรับโค้ดของคุณเอง

HTTPS กับ JSON ธรรมดา ใช้ได้กับ server, script และ build pipeline อ่านคลังไอคอนชุดเดียวกัน และหักเครดิตด้วยโค้ดเดียวกับเว็บและ MCP server

  • การยืนยันตัวตน: ใช้ API key ส่วนตัวตัวเดียวกับ MCP — Authorization: Bearer blu_live_… — จากบัญชี Studio คีย์ของบัญชี Free หรือ Designer จะได้ 403 plan_not_allowed
  • เรียกได้ 5,000 ครั้งต่อเดือนต่อบัญชี นับแยกจาก MCP ส่วน GET /api/v1/me ไม่นับ และบอกว่าเหลือกี่ครั้ง
  • เครดิตคิดเหมือนบนเว็บทุกประการ: ดาวน์โหลด 256px ฟรี ภาพความละเอียดสูงหักเครดิตครั้งแรกที่เอาไอคอนนั้น ครั้งต่อไปฟรี
  • ยังไม่มี endpoint สำหรับสร้างไอคอน ให้สร้างบนเว็บ หรือใช้ generate_icon ของ MCP server
https://realisticicon.com/api/v1

เก็บคีย์ไว้ฝั่ง server คีย์ใช้เครดิตของคุณได้ จึงควรเรียก API จาก backend ไม่ใช่จากหน้าเว็บ และทุก POST ต้องส่ง Content-Type: application/json ไม่อย่างนั้นคำขอจะถูกปฏิเสธก่อนถึง API

# search
curl "https://realisticicon.com/api/v1/icons?q=fox&limit=5" \
  -H "Authorization: Bearer blu_live_YOUR_KEY"

# download — charged the first time you take this icon
curl -X POST "https://realisticicon.com/api/v1/icons/ICON_ID/download" \
  -H "Authorization: Bearer blu_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"size":"512"}'

Endpoint ของ REST

มี 6 endpoint รับและส่งเป็น JSON

MethodPathทำอะไรเครดิต
GET/api/v1/iconsค้นหาหรือไล่ดูไอคอน พารามิเตอร์: q, category, style (realistic · isometric · clay), kind (image · video), collection, page, limit (สูงสุด 50 ค่าเริ่มต้น 24), seed, locale ผลแบบไล่ดูจะส่ง seed กลับมา ให้ส่งค่านั้นไปกับหน้าถัดไปเพื่อให้ลำดับไม่เปลี่ยน—
GET/api/v1/icons/{id}ไอคอนหนึ่งชิ้น: คำอธิบาย แท็ก prompt ที่ใช้สร้าง ขนาดที่มี รูปตัวอย่าง 256px และลิงก์หน้าไอคอน—
POST/api/v1/icons/{id}/downloadBody {"size": "256" | "512" | "original"} (ค่าเริ่มต้น 512) ได้ URL ไฟล์ บอกว่าครั้งนี้หักเครดิตไหม และยอดเครดิตที่เหลือ256px ฟรี ส่วน 512px หรือต้นฉบับ: 1 เครดิตในครั้งแรกของไอคอนนั้น ครั้งต่อไปฟรี วันละไม่เกิน 60 ไอคอนใหม่
GET/api/v1/collectionscollection ที่คัดไว้ กรองตาม theme ได้ เอา id ของ collection ไปใส่ collection= ใน /icons เพื่อดูไอคอนในชุดนั้น—
GET/api/v1/generationsรายการที่คุณสร้างด้วย Studio ล่าสุด พร้อม URL รูป (limit สูงสุด 40)—
GET/api/v1/meแพลน เครดิต ขนาดดาวน์โหลดสูงสุด และจำนวนครั้งที่เรียก API เดือนนี้ ไม่นับรวมใน 5,000 ครั้ง—

GET /api/v1 ไม่ต้องใช้คีย์ จะได้การ์ด JSON บอกรายชื่อ endpoint ทั้งหมด ใส่ locale=th (หรือภาษาอื่นของเว็บ) เพื่อให้ชื่อไอคอนและลิงก์หน้าเป็นภาษานั้น

Error และข้อจำกัดของ REST

ใช้ status code มาตรฐาน และรูปแบบ JSON แบบเดียว

ทุก error มีหน้าตาแบบ { "error": { "code": "…", "message": "…" } } ให้เขียนโค้ดแยกกรณีด้วย code ซึ่งจะไม่เปลี่ยน ส่วน message เขียนไว้ให้คนอ่าน และอาจเปลี่ยนถ้อยคำได้

Statuscodeความหมาย
400invalid_requestพารามิเตอร์ขาดหรือเกินช่วง ข้อความจะบอกชื่อพารามิเตอร์
401missing_api_key · invalid_api_keyไม่ได้ส่งคีย์ หรือคีย์ผิด ถูกหมุนเวียน หรือถูกเพิกถอนแล้ว
402insufficient_creditsเครดิตไม่พอสำหรับการดาวน์โหลดนั้น เติมเครดิตได้ที่หน้า Billing
403plan_not_allowed · over_plan_capบัญชีของคีย์ไม่ใช่แพลน Studio หรือขนาดที่ขอเกินเพดานของแพลน
404not_foundไม่มีไอคอน collection หรือ endpoint นั้น
405method_not_allowedpath ถูกแต่ method ผิด ดู method ที่ถูกได้จาก header Allow
429rate_limited · monthly_limit_reached · daily_limit_reachedเกิน 300 คำขอต่อนาทีต่อคีย์ (รอตาม Retry-After) หรือเกิน 5,000 ครั้งต่อเดือน (รีเซ็ตตาม X-Quota-Reset) หรือเกินเพดานดาวน์โหลดไอคอนใหม่ต่อวันของแพลน (รีเซ็ตเที่ยงคืน UTC)
5xxupstream_unavailable · internal_errorปัญหาฝั่งเรา ลองใหม่ได้อย่างปลอดภัย ไอคอนเดิมจะไม่ถูกหักเครดิตซ้ำ
Header ที่ส่งกลับทุกครั้ง
  • X-RateLimit-Limit และ X-RateLimit-Remaining: ของนาทีนี้
  • X-Quota-Limit, X-Quota-Remaining และ X-Quota-Reset: ของเดือนนี้ (UTC)
  • Retry-After: มากับทุก 429 หน่วยเป็นวินาที

พร้อมลองหรือยัง

ถ้าอยู่บนแพลน Studio: สร้างคีย์ แล้วเพิ่ม URL ในผู้ช่วย AI หรือเรียก REST API จากโค้ดของคุณได้เลย