Renderqo Public API — คู่มือการใช้งาน (สำหรับผู้ใช้)

คู่มือนี้คือ API สาธารณะ (ไม่เข้ารหัส) สำหรับเรียกใช้งาน Renderqo จากภายนอก เช่น n8n, script,
backend ของคุณเอง ครอบคลุม ทุก provider และทุกโหมด — ใช้เส้นทางเวอร์ชัน /api/v1/*

🔀 เลือก Local / Public ที่ปุ่มด้านบนของหน้านี้ เพื่อสลับ base URL ของตัวอย่างทั้งหมด
— endpoint, พารามิเตอร์ และ response เหมือนกันทุกอย่าง ต่างแค่ host:
- Local — http://127.0.0.1:6699 : เรียก Renderqo บนเครื่องเดียวกัน (dev / n8n ในเครื่อง)
- Public — https://api.renderqo.com : เรียกจากภายนอก (production) ผ่าน cloud relay
*(job ยังทำงานบน Renderqo ที่เครื่องของคุณเสมอ — cloud แค่รับคำขอแล้วส่งต่อไปเครื่องที่ระบุด้วย X-Device-Id,
รอผลแล้วส่งกลับ; เครื่องนั้นต้องเปิดแอปและสถานะ Running + ล็อกอินไลเซนส์อยู่. ไม่ต้องเปิดเครื่องออกเน็ตเอง)*
(ไฟล์ผลลัพธ์เมื่อเรียกผ่าน Public จะเสิร์ฟจาก https://api.renderqo.com/api/v1/files/... แทน host ในเครื่อง — เก็บมากสุด 10 งานต่อ Device ID)

• Base URL (ค่าเริ่มต้น): http://127.0.0.1:6699
• เส้นทาง: /api/v1/*
• รูปแบบ: JSON ธรรมดา (ไม่เข้ารหัส) · ต้องแนบ API key + X-Device-Id ทุก request (ดู §0)
• ข้อกำหนด: Renderqo (แอป Desktop) ต้องเปิดและสถานะ Running

⚠️ ทุก provider ต้องมี Chrome Extension เชื่อมต่ออยู่ (รวม google_image_search) — แค่เปิดเบราว์เซอร์ที่ติดตั้งส่วนขยายไว้ ไม่ต้องเปิดหน้าต่างใดของส่วนขยาย
ระบบถือว่า "ออนไลน์สมบูรณ์" ก็ต่อเมื่อ แอป Renderqo เปิด (Running) + Extension เชื่อมต่อ
ถ้า extension ไม่ได้เปิด การสร้างงานจะถูกปฏิเสธพร้อมข้อความ "ระบบยังออนไลน์ไม่สมบูรณ์ กรุณาตรวจสอบอีกครั้ง" (no_extension_connected)

0) Authentication — ต้องมี API key + Device ID 🔑

ทุก request ไปยัง /api/v1/* ต้องแนบ 2 header:

Authorization: Bearer rqo_live_xxxxxxxxxxxx
X-Device-Id: dev-xxxxxxxxxxxxxxxx

API key (Authorization)

• สร้าง/จัดการ key ที่ me.renderqo.com → API Keys — สร้างได้หลายอัน ตั้งชื่อแยก และดู สถิติแยกต่อ key ได้
• key จะแสดง ครั้งเดียว ตอนสร้าง — เก็บไว้ให้ดี (เก็บเฉพาะ hash ในระบบ)
• ไม่มี / ผิด / ถูกเพิกถอน → ตอบ 401 (api_key_required หรือ api_key_invalid)
• เพิกถอน key แล้วมีผลภายในไม่กี่นาที (sync ลง renderqo-server อัตโนมัติ)
• รองรับ X-API-Key: <key> แทน Bearer ได้เช่นกัน

Device ID (X-Device-Id) — ระบุ "เครื่องปลายทาง"

• API key เป็นของ สมาชิก จึงใช้ได้กับ ทุกเครื่อง ที่ลง license เดียวกัน — X-Device-Id คือสิ่งที่บอกว่า trigger นี้ให้วิ่งที่ เครื่องไหน
• หา Device ID ได้ใน Renderqo Extension → ไอคอนผู้ใช้ (มุมขวาบน) → คัดลอก Device ID (ค่ารูปแบบ dev-…)
• เครื่องจะรับงานเฉพาะเมื่อ X-Device-Id ตรงกับเครื่องนั้น
• ไม่ส่ง header → 400 (device_id_required) · ส่งมาไม่ตรงเครื่อง → 403 (device_mismatch)

ℹ️ ตัวอย่าง curl ในเอกสารนี้ละ Authorization + X-Device-Id เพื่อความกระชับ — ของจริงต้องแนบทั้ง 2 ทุกครั้ง

ตัวอย่างเต็ม (คัดลอกไปใช้ได้ทันที — เติม key + device id ของคุณ):

curl -X POST http://127.0.0.1:6699/api/v1/jobs \
  -H "Authorization: Bearer rqo_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Device-Id: dev-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"provider":"chatgpt","type":"image","prompt":"a red sports car","ratio":"4:3"}'

ℹ️ ตัวอย่างใช้ async (/api/v1/jobs) — สร้างงานแล้วได้ jobId กลับมาทันที จากนั้น poll GET /api/v1/jobs/:id จนได้ status:"done"

🔎 เจอ 401/400 ทั้งที่มี key แล้ว? เช็ค 4 ข้อนี้ (เป็นสาเหตุเกือบทั้งหมด เพราะตัวอย่าง curl ด้านล่างตัด 2 header นี้ออก):
1. มี Bearer นำหน้า ใน Authorization (เว้นวรรค 1 ช่อง) — ไม่มี → api_key_required
2. key เต็มขึ้นต้น rqo_live_ และยาว 49 ตัวอักษร (rqo_live_ + 40 hex) — copy ไม่ครบ/ตก prefix → api_key_invalid (แม้ 4 ตัวท้ายตรงก็ตาม)
3. มี X-Device-Id — key ผ่านแต่ไม่มี header นี้ → 400 device_id_required
4. device id ตรงกับเครื่องที่ Renderqo รันอยู่ (ดูใน Extension → ไอคอนผู้ใช้) — ไม่ตรง → 403 device_mismatch

ลำดับการตรวจ: key ก่อน (api_key_*) → แล้วค่อย device (device_*) — แก้ทีละชั้น

0.5) Browser Profile (หลายเบราว์เซอร์) 🌐

เปิดส่วนขยาย Renderqo ได้ หลาย browser profile พร้อมกัน — แต่ละโปรไฟล์มี Browser ID ของตัวเอง
(รูปแบบ br- + 6 hex เช่น br-3f8a2c) และมีสถานะ login ต่อ provider แยกกัน งาน**รันขนานกันได้
โปรไฟล์ละ 1 งาน**

หา Browser ID ได้ 3 ทาง:

1. แดชบอร์ดในแอป Renderqo — การ์ดส่วนขยายแสดงทุกเบราว์เซอร์ที่เชื่อมต่อ พร้อมปุ่มคัดลอก id
2. popup ของส่วนขยาย (คลิกไอคอน Renderqo ในเบราว์เซอร์นั้น) — แสดง id ของตัวเอง
3. ทาง API:

curl -s http://127.0.0.1:6699/api/v1/browsers \
  -H "Authorization: Bearer rqo_live_xxx" -H "X-Device-Id: dev-xxx"

{ "ok": true, "browsers": [
    { "id": "br-0a8a9d", "label": "หลัก", "version": "0.0.100", "connectedAt": "2026-08-02T01:00:00.000Z",
      "busy": false, "debuggerBlocked": false,
      "providers": { "google_flow": "in", "meta_ai": "in", "chatgpt": "in", "grok": "out", "google_image_search": "in" } },
    { "id": "br-0f70a6", "label": null, "version": "0.0.100", "connectedAt": "2026-08-02T01:02:00.000Z",
      "busy": true, "debuggerBlocked": false,
      "providers": { "google_flow": "in", "meta_ai": "in", "chatgpt": "in", "grok": "in", "google_image_search": "in" } }
] }

Public (https://api.renderqo.com) ตอบเส้นนี้จาก snapshot ล่าสุดที่เครื่องส่งขึ้นมา (เครื่อง
แนบรายการเบราว์เซอร์ไปกับ heartbeat ทุกครั้งที่ poll ~3 วินาที) — ข้อมูลจึงช้ากว่าของจริงได้ไม่เกิน
~1 รอบ poll · ถ้าแอปบนเครื่องไม่ออนไลน์ = 503 device_offline (โค้ดเดียวกับตอนสร้างงาน)

การเลือกเบราว์เซอร์ตอนสร้างงาน:

• ไม่ส่ง browser (ค่าปกติ) → ระบบจัดคิวอัตโนมัติ: เลือกเบราว์เซอร์ที่ว่าง + ล็อกอิน provider นั้นอยู่

(ตัวที่ login แล้วถูกเลือกก่อน · ตัวที่ logout ถูกข้าม · กระจายงานแบบ least-recently-used)

• ส่ง browser: "br-xxxxxx" → งานรันบนเบราว์เซอร์ตัวนั้นเท่านั้น — ถ้าไม่ว่างงานจะรอคิวของตัวนั้น ·

ถ้าไม่ได้เชื่อมต่อ = 503 browser_not_connected ทันที (ไม่เข้าคิวรอ)

• ผลลัพธ์ของงานบอกเสมอว่ารันที่ไหน: GET /api/v1/jobs/:id ฝั่ง Local (/private/jobs/:id) มี

browser (ที่ขอ) + browserId (ที่รันจริง)

# ตัวอย่าง: บังคับรันบนโปรไฟล์ br-0f70a6
curl -s -X POST http://127.0.0.1:6699/api/v1/jobs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer rqo_live_xxx" -H "X-Device-Id: dev-xxx" \
  -d '{"provider":"grok","type":"image","prompt":"a red umbrella","ratio":"1:1","browser":"br-0f70a6"}'

1) สรุป Endpoints

2) พารามิเตอร์ของการสร้างงาน (POST /api/v1/jobs)

คอลัมน์ รองรับโดย = provider ที่ใช้ฟิลด์นั้น (provider อื่นส่งมาจะถูกเมิน ไม่ error). ตัวย่อ:
Flow=google_flow · Meta=meta_ai · GPT=chatgpt · ImgSearch=google_image_search · Grok=grok

โมเดลของ google_flow

ส่ง model เป็น ชื่อโมเดลตรงตามที่ Flow แสดงใน dropdown (จับคู่แบบตรงตัว — แยก Veo 3.1 - Lite
กับ Veo 3.1 - Lite [Lower Priority] ออกจากกันได้). ถ้าไม่ส่ง model จะใช้ค่าเริ่มต้นของ Flow ตามบัญชี.
รายการที่ใช้ได้ ขึ้นกับ tier ของบัญชี + lineup ปัจจุบันของ Flow (เปลี่ยนได้) — ถ้าส่งชื่อที่บัญชีนั้นไม่มี
ระบบจะคงค่าเริ่มต้นไว้แทนที่จะล้มงาน. ตัวอย่างที่พบบ่อย:

รองรับ shorthand ด้วย (จับคู่คีย์เวิร์ด): fast/quality/lite → Veo 3.1 ตัวนั้น · omni/flash → Omni Flash · nano/banana → Nano Banana Pro

3) รูปแบบการตอบกลับ (v1)

สร้างงาน (POST /api/v1/jobs)

{
  "ok": true,
  "jobId": "cmpz...",
  "status": "queued"
}

(ถ้าส่ง callbackUrl มาด้วย จะมี "callbackUrl": "..." กลับมาด้วย)

ดูสถานะ/ผลลัพธ์ (GET /api/v1/jobs/:id)

{
  "ok": true,
  "status": "done",
  "message": "job is done",
  "media_urls": [
    "http://127.0.0.1:6699/files/cmpz.../chatgpt_0.png"
  ]
}

• status: running \| done \| fail \| canceled — จบแล้ว = done/fail/canceled (หยุด poll ได้)

· queued โผล่เฉพาะใน response ตอน สร้างงาน (POST /api/v1/jobs) เท่านั้น — ตอน poll งานที่ยังรอคิวตอบเป็น running

• ขณะยังไม่เสร็จ (รอคิว/กำลังสร้าง) → status:"running", media_urls: []
• ล้มเหลว → ok:false, status:"fail"
• ถูกยกเลิก (ผ่าน POST /api/v1/jobs/:id/cancel) → status:"canceled", ok:true, media_urls: []
• ไฟล์ผลลัพธ์เสิร์ฟผ่าน http://127.0.0.1:6699/files/:jobId/:fileName (เปิด/ดาวน์โหลดได้ตรง ไม่ต้อง auth)

ภาพ thumbnail ของงานวิดีโอ

งาน type:"video" จะมีภาพ thumbnail แถมมาด้วย — ระบบดึงเฟรมที่ วินาทีที่ 2 ของแต่ละคลิปมาเก็บเป็นไฟล์
.jpg (สั่ง 3 คลิป = ได้ 3 ภาพ) เพื่อให้เอาไปแสดงในหน้ารายการได้โดยไม่ต้องโหลดวิดีโอทั้งไฟล์

{
  "ok": true,
  "status": "done",
  "media_urls": ["https://api.renderqo.com/files/cmpz.../google_flow_0.mp4"],
  "thumbnail_urls": ["https://api.renderqo.com/files/cmpz.../google_flow_0_thumb.jpg"]
}

• thumbnail_urls อยู่ ระดับเดียวกับ media_urls และ index ตรงกัน — thumbnail_urls[i] คือภาพของ media_urls[i]
• งานภาพจะไม่มีคีย์นี้เลย (ไม่ใช่อาเรย์ว่าง) — เช็คด้วยการมี/ไม่มีคีย์ได้
• คลิปที่ดึงเฟรมไม่สำเร็จจะเป็น null ในตำแหน่งนั้น เพื่อรักษาลำดับให้ตรงกับ media_urls

⇒ อย่าใช้ thumbnail_urls[i] โดยไม่เช็ค null

• คลิปที่สั้นกว่า 2 วินาที ระบบถอยไปดึงที่วินาที 1 หรือวินาทีแรกให้อัตโนมัติ
• ⚠️ ดึงเฟรมไม่สำเร็จไม่ทำให้งานล้มเหลว — งานยังเป็น done และได้วิดีโอครบ

เปลี่ยนจากสเปกเดิม (2026-08-04): เดิมเก็บซ้ำ 2 ที่ (result.thumbnail_urls + result.files[].thumbnail
+ thumbnailAtSec) ตอนนี้เหลือ thumbnail_urls ที่ระดับบนสุดที่เดียว · result.files[] ไม่มีฟิลด์
เกี่ยวกับ thumbnail แล้ว

4) ตัวอย่างตาม provider/โหมด

4.1 ChatGPT — สร้างรูป (image เท่านั้น)

curl -X POST http://127.0.0.1:6699/api/v1/jobs \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "chatgpt",
    "type": "image",
    "prompt": "a cute corgi puppy in a field, studio lighting",
    "ratio": "4:3",
    "deleteChat": true
  }'

• รองรับ ratio: 1:1, 3:4, 9:16, 4:3, 16:9 (ค่าเริ่มต้นแนะนำ 4:3)
• แนบภาพอ้างอิงได้สูงสุด 6 ภาพผ่าน image_ref
• count ถูกล็อกที่ 1
• deleteChat: true = ลบ conversation ที่สร้างขึ้นบน ChatGPT ทิ้งหลังงานจบ (ทั้งสำเร็จและล้มเหลว) เพื่อไม่ให้แชทค้างสะสมในบัญชี · ค่าเริ่มต้น false · เป็น best-effort — ถ้าลบไม่สำเร็จงานยังคืนผลปกติ

# แนบภาพอ้างอิง
curl -X POST http://127.0.0.1:6699/api/v1/jobs \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "chatgpt", "type": "image",
    "prompt": "turn this into a watercolor painting",
    "ratio": "1:1",
    "image_ref": ["https://example.com/photo.jpg"]
  }'

4.2 Google Flow — สร้างรูป

curl -X POST http://127.0.0.1:6699/api/v1/jobs \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google_flow",
    "type": "image",
    "prompt": "a minimal product photo of a perfume bottle",
    "ratio": "1:1",
    "count": 2,
    "model": "Nano Banana Pro",
    "image_ref": ["https://example.com/ref1.jpg"]
  }'

4.3 Google Flow — สร้างวิดีโอปกติ (videoMode = ingredients, ค่าเริ่มต้น)

curl -X POST http://127.0.0.1:6699/api/v1/jobs \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google_flow",
    "type": "video",
    "prompt": "a cinematic rainy street at night with neon reflections",
    "ratio": "16:9",
    "count": 1,
    "model": "Veo 3.1 - Fast"
  }'

วิดีโอปกติใช้ videoMode=ingredients เป็นค่าเริ่มต้น (ไม่ต้องส่งก็ได้) — ภาพแนบ (image_ref) ไม่บังคับ

4.4 Google Flow — วิดีโอจากเฟรม (videoMode = frames)

curl -X POST http://127.0.0.1:6699/api/v1/jobs \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google_flow",
    "type": "video",
    "videoMode": "frames",
    "prompt": "camera slowly pushes in as the character smiles",
    "ratio": "16:9",
    "startFrame": "https://example.com/first.jpg",
    "endFrame": "https://example.com/last.jpg",
    "project_name": "My Project"
  }'

• type=video + videoMode=frames — startFrame จำเป็น, endFrame ไม่บังคับ
• startFrame / endFrame รับได้ทั้ง URL ภายนอก และ URL ของ server ตัวเอง (http://127.0.0.1:6699/uploads/… หรือ http://127.0.0.1:6699/files/…) — ระบบจะอ่านไฟล์จาก disk โดยตรงโดยไม่ต้อง HTTP roundtrip
• project_name — ถ้าส่งมา ระบบจะ find-or-create โปรเจคชื่อนี้ใน Flow และเปลี่ยนชื่อโปรเจคหลังสร้างเสร็จ; ถ้าไม่ส่ง = สร้างโปรเจคใหม่ทุกครั้ง

4.5 Google Flow — Ingredients to Video

curl -X POST http://127.0.0.1:6699/api/v1/jobs \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google_flow",
    "type": "video",
    "videoMode": "ingredients",
    "prompt": "blend these references into a dynamic scene",
    "ratio": "16:9",
    "image_ref": [
      "https://example.com/a.jpg",
      "https://example.com/b.jpg"
    ]
  }'

• image_ref ไม่บังคับ สำหรับโหมด Ingredients — ถ้าไม่ใส่ จะสร้างวิดีโอจาก prompt ล้วน (ต่างจากโหมด Frames ที่ startFrame จำเป็น)

4.6 Google Flow — ดาวน์โหลดความละเอียดสูง (Upscale)

curl -X POST http://127.0.0.1:6699/api/v1/jobs \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google_flow", "type": "video",
    "prompt": "a golden retriever running on the beach",
    "ratio": "16:9",
    "downloadQuality": "1080p"
  }'

• video: original(720p) \| 1080p(ฟรี) \| 4k(เสีย credit)
• image: original(1k) \| 2k \| 4k

4.7 Meta AI — รูป/วิดีโอ

curl -X POST http://127.0.0.1:6699/api/v1/jobs \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "meta_ai",
    "type": "image",
    "prompt": "a futuristic cyberpunk city skyline",
    "ratio": "9:16"
  }'

• type: image หรือ video
• ratio: 1:1, 9:16, 16:9
• ไม่ต้องส่ง count — Meta AI กำหนดจำนวนไม่ได้ ระบบจะสร้าง ~4 รายการอัตโนมัติ และคืนผลลัพธ์ทุกรายการใน media_urls (ถ้าส่ง count มาจะถูกเมิน)
• image_ref (ไม่บังคับ): แนบภาพอ้างอิงได้ สูงสุด 6 URL — ระบบแนบผ่านตัวเลือกอัปโหลดของ composer ให้อัตโนมัติ

4.8 Google Image Search — ค้นหารูปตามคีย์เวิร์ด

curl -X POST http://127.0.0.1:6699/api/v1/jobs \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google_image_search",
    "type": "image",
    "prompt": "golden retriever puppy",
    "count": 5
  }'

• prompt = คีย์เวิร์ดที่ต้องการค้นหา
• count = จำนวนรูป 1-10
• ระบบจะค้นหาบน Google Images แล้วดาวน์โหลดภาพต้นทางมาเก็บ → คืนเป็น media_urls
• ไม่ต้องใช้ ratio / model / image_ref

⚠️ ข้อควรรู้: ต้องมี Extension เชื่อมต่ออยู่ เช่นเดียวกับ provider อื่น (ไม่ได้เชื่อมต่อ → no_extension_connected)
และต้อง login Google ในเบราว์เซอร์ที่ติดตั้งส่วนขยาย — การค้นหาทำบนแท็บจริงในเบราว์เซอร์นั้น จึงไม่โดนระบบกันบอท (/sorry / unusual traffic)

บางเว็บต้นทางห้าม hotlink ระบบจะข้ามรูปนั้นและใช้รูปถัดไปจนครบจำนวน

4.9 Grok — สร้างรูป (โหมดเร็ว/คุณภาพ)

curl -X POST http://127.0.0.1:6699/api/v1/jobs \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "grok",
    "type": "image",
    "prompt": "a neon cyberpunk fox, highly detailed",
    "model": "quality",
    "ratio": "2:3"
  }'

• model = โหมดสร้างรูป: speed (เร็ว) หรือ quality (คุณภาพ) — ค่าเริ่มต้น quality
• ratio = 2:3 \| 3:2 \| 1:1 \| 9:16 \| 16:9
• ไม่ต้องส่ง count — ผลลัพธ์ 1 รายการเสมอ (ถ้าส่ง count มาจะถูกเมิน)
• สร้างเสร็จระบบเปิดภาพแรก → กดปุ่ม Download → ได้ไฟล์จริงแล้วตอบกลับทันที
• ⏱️ timeout การสร้าง 15 นาที (รูป) — เกินแล้วยังไม่เสร็จ งานจะ fail

4.10 Grok — สร้างวิดีโอ (resolution + duration + extend)

curl -X POST http://127.0.0.1:6699/api/v1/jobs \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "grok",
    "type": "video",
    "prompt": "a paper boat sailing down a rainy street, cinematic",
    "resolution": "1080p",
    "duration": "10s",
    "ratio": "16:9",
    "extend": true
  }'

• resolution = 720p (สร้าง 720p ตรง) \| 1080p (สร้าง 480p แล้ว upscale อัตโนมัติ) — ค่าเริ่มต้น 720p
• duration = 6s \| 10s — ค่าเริ่มต้น 10s
• extend = true/false — ต่อความยาว 1 ครั้งหลังสร้างเสร็จ (ค่าเริ่มต้น false)
• ratio = 2:3 \| 3:2 \| 1:1 \| 9:16 \| 16:9
• ไม่ต้องส่ง count — ผลลัพธ์ 1 รายการเสมอ (ถ้าส่ง count มาจะถูกเมิน)
• สร้างเสร็จระบบกดปุ่ม Download ดาวน์โหลดไฟล์จริงแล้วตอบกลับทันที
• ⏱️ timeout การสร้าง 25 นาที (วิดีโอ) — เกินแล้วยังไม่เสร็จ งานจะ fail · เวลา upscale/extend/ดาวน์โหลด ไม่นับรวม ในนี้ (มีงบแยกให้อีก)

⚠️ ต้องมี Extension เชื่อมต่ออยู่ + login grok.com ในเบราว์เซอร์ (ไม่งั้น no_extension_connected / provider_not_logged_in)

🖼️ ภาพต้นฉบับ (full-res): ระบบ ตามไปหน้าต้นทาง (source page) ของแต่ละผลลัพธ์ → ดึง og:image (ภาพต้นฉบับ);
ถ้าไม่ได้ → upgrade URL ของภาพ (Twitter/Pinterest/Wikimedia/Imgur/YouTube/Reddit แก้ขนาดตรงๆ ได้แม่น) → สุดท้ายคือ thumbnail
(API สาธารณะคืน media_urls เท่านั้น — ไม่มี metadata ต่อไฟล์ / source URL รายรูป)

5) การติดตามงาน (Polling)

สำหรับงานที่ใช้เวลานาน (โดยเฉพาะวิดีโอ) แนะนำ (poll ทุก 5 วินาทีขึ้นไป — ระบบ cache สถานะ 5 วินาที):

# 1) สร้างงาน
RESP=$(curl -s -X POST http://127.0.0.1:6699/api/v1/jobs \
  -H "Content-Type: application/json" \
  -d '{"provider":"google_flow","type":"video","prompt":"a calm ocean at sunset","ratio":"16:9"}')
JOB_ID=$(echo "$RESP" | python3 -c "import sys,json;print(json.load(sys.stdin)['jobId'])")

# 2) วน poll จนกว่าจะ done/fail
while true; do
  J=$(curl -s http://127.0.0.1:6699/api/v1/jobs/$JOB_ID)
  STATUS=$(echo "$J" | python3 -c "import sys,json;print(json.load(sys.stdin)['status'])")
  echo "status: $STATUS"
  [ "$STATUS" = "done" ] && echo "$J" && break
  [ "$STATUS" = "fail" ] && echo "$J" && break
  sleep 5
done

หรือใช้ callbackUrl ให้ระบบยิงผลลัพธ์กลับมาหาคุณเองเมื่อเสร็จ:

curl -X POST http://127.0.0.1:6699/api/v1/jobs \
  -H "Content-Type: application/json" \
  -d '{
    "provider":"chatgpt","type":"image","prompt":"a red sports car",
    "callbackUrl":"https://your-server.com/renderqo-callback"
  }'

Payload ที่ยิงไปยัง callbackUrl (เมื่องานเสร็จ/ล้มเหลว) — มี media_urls ของผลลัพธ์:

{
  "ok": true,
  "jobId": "cmpz...",
  "status": "done",
  "media_urls": ["http://127.0.0.1:6699/files/.../chatgpt_0.png"],
  "clientRequestId": "your-ref-123",
  "error": null
}

งานวิดีโอจะมี thumbnail_urls เพิ่มมาข้าง media_urls (index ตรงกัน) แบบเดียวกับ GET /api/v1/jobs/:id

6) Error & ข้อผิดพลาดที่พบบ่อย

ทุก error ตอบกลับรูปแบบ:

{ "ok": false, "error": { "code": "...", "message": "...", "retryable": true } }

ตัวอย่างเฉพาะ google_image_search:

• Google blocked the automated search (/sorry) → เปิด Extension + login Google
• Found images but could not download any → เว็บต้นทางบล็อก hotlink (ลอง keyword อื่น/เพิ่ม count)

7) ตารางสรุปความสามารถต่อ provider

Grok — โหมด + ตัวเลือก

ภาพอ้างอิง (input references) ของ Grok: เป็นตัวเลือกเสริม ไม่จำเป็นต้องแนบ · แนบได้สูงสุด 5 รูป · รองรับ ไฟล์รูปภาพเท่านั้น (ไม่รับวิดีโอ) · ใช้ได้ทั้งโหมด image และ video · รูปความละเอียดต่ำอาจทำให้คุณภาพผลลัพธ์ลดลง

Grok video — resolution / upscale / extend:
- resolution: "720p" → สร้างที่ 720p ตรงๆ
- resolution: "1080p" → สร้างที่ 480p แล้ว upscale อัตโนมัติ (Grok ให้ upscale เฉพาะวิดีโอที่สร้างด้วย 480p) → ได้ผลลัพธ์ความละเอียดสูงขึ้น · ใช้เวลานานกว่า
- extend: true → หลังสร้างเสร็จจะกด Extend ต่อความยาวให้ 1 ครั้ง (ใช้ได้ทุก resolution)
- ผลลัพธ์ 1 รายการเสมอ ทั้งภาพและวิดีโอ · สร้างเสร็จระบบกดปุ่ม Download ดาวน์โหลดไฟล์จริงแล้วตอบกลับทันที

ตัวอย่าง: Grok image พร้อมภาพอ้างอิง

curl -X POST http://127.0.0.1:6699/api/v1/jobs \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "grok",
    "type": "image",
    "prompt": "blend these into a surreal poster",
    "model": "quality",
    "ratio": "1:1",
    "image_ref": ["https://example.com/a.png", "https://example.com/b.jpg"]
  }'

8) หมายเหตุสำคัญ

1. ต้องออนไลน์สมบูรณ์ = แอป Running + Extension เชื่อมต่อ (แค่เปิดเบราว์เซอร์ที่ติดตั้งส่วนขยายไว้ ส่วนขยายเชื่อมต่อเอง) — บังคับ ทุก provider (รวม google_image_search). ถ้า extension ไม่ได้เชื่อมต่อ การสร้างงานถูกปฏิเสธทันทีด้วย no_extension_connected ("ระบบยังออนไลน์ไม่สมบูรณ์ กรุณาตรวจสอบอีกครั้ง")
2. Public (cloud relay): cloud ตรวจสถานะเครื่องปลายทาง (X-Device-Id) จาก heartbeat ของ relay poll ก่อนรับงาน — แอปไม่ออนไลน์ → 503 device_offline; แอปออนไลน์แต่ extension ปิด → 503 no_extension_connected (ทั้งคู่ตอบทันทีตอนเรียก ไม่ปล่อยให้งานค้าง)
3. Rate limit: 10 งาน/นาที, 100 คำขอ/นาที (เชิงเทคนิค) — แยกจาก โควต้ารายวันของแพ็ก (เช่น ทดลองใช้งาน 100 งาน/วัน → 429 quota_exceeded)
4. ไฟล์ผลลัพธ์ (Public) เก็บมากสุด 10 งานต่อ Device ID — งานเก่าสุดถูกลบเมื่อมีงานใหม่เกินจำนวน; ดาวน์โหลดไว้เองถ้าต้องใช้ระยะยาว
5. วิดีโอใช้เวลานาน (หลายนาที) — ใช้ async + poll (GET /api/v1/jobs/:id ทุก 5 วินาทีขึ้นไป) หรือ callbackUrl