Chat API ของ Rivya

ใช้ POST /api/v1/chat/completions เพื่อรับคำตอบแชตที่สมบูรณ์หนึ่งรอบแบบไม่สตรีม หรือใช้ POST /api/v1/chat/completions/stream เพื่อรับเหตุการณ์ที่เซิร์ฟเวอร์ส่งมาอย่างต่อเนื่อง (SSE)

Chat API ทำงานบนเซสชัน หากไม่ส่ง session_id ระบบจะสร้างเซสชันแชต API ใหม่ ส่ง session_id ที่ได้รับกลับมาเพื่อสนทนาต่อในเซสชันเดิม

หน้านี้อธิบายสัญญา Public API v1 ที่ระบบรองรับ การเรียกใช้งานจริงยังต้องเปิด Public API ในระบบที่นำไปใช้งาน ใช้คีย์ API ของบัญชีที่ใช้งานได้ และเลือกโมเดลที่มีสถานะ API พร้อมใช้ โปรดตรวจรายการโมเดลปัจจุบันก่อนส่งคำขอในระบบจริง

ขอบเขตปัจจุบัน

Chat API v1 รองรับ:

• คำตอบจากผู้ช่วยแบบไม่สตรีม

• การสตรีม SSE ด้วย text/event-stream

• เซสชันแชตที่สร้างผ่าน API

• การกันเครดิตบัญชีล่วงหน้าและการสรุปยอดสุดท้ายตาม โทเคน

• การค้นหาเว็บ ระดับการใช้เหตุผล และโหมดความคิด เมื่อโมเดลที่เลือกรองรับ

• รูปภาพแนบผ่านค่า file_id จาก Files API

Chat API v1 ไม่รองรับ:

• ประวัติ messages แบบดิบที่ผู้ใช้ส่งเอง

• การสนทนาต่อจากเซสชันแชตที่มีเฉพาะใน Studio

• URL ไฟล์แนบภายนอกตามอำเภอใจ

• เหตุการณ์ เว็บฮุก ของ การสนทนา

ขอบเขตสิทธิ์ที่จำเป็น

ใช้คีย์ API ที่มี:

chat:create
chat:read

คีย์ใหม่ที่สร้างในหน้าการตั้งค่าจะมีขอบเขตสิทธิ์ทั้งสองรายการนี้โดยค่าเริ่มต้น ส่วนคีย์รุ่นเก่าอาจต้องสร้างใหม่ก่อนเรียกใช้ API แชต

สร้าง การสนทนา การทำงานเสร็จ

curl https://rivya.ai/api/v1/chat/completions \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: chat-turn-001" \
  -d '{
    "model": "claude-sonnet-5-chat",
    "message": "Write a concise launch plan for a new product image campaign",
    "client_request_id": "chat-001"
  }'

การตอบกลับ:

{
  "id": "chatcmpl_...",
  "object": "chat.completion",
  "session_id": "session_id",
  "model": "claude-sonnet-5-chat",
  "created_at": "2026-05-11T00:00:00.000Z",
  "message": {
    "id": "assistant_message_id",
    "role": "assistant",
    "content": "..."
  },
  "usage": {
    "input_tokens": 1200,
    "output_tokens": 320,
    "total_tokens": 1520
  },
  "credits": {
    "reserved": 3,
    "final": 2
  }
}

สตรีม การสนทนา การทำงานเสร็จ

ใช้ POST /api/v1/chat/completions/stream เมื่อเซิร์ฟเวอร์ต้องการรับส่วนข้อความจากผู้ช่วยทันทีที่ส่งมา:

curl -N https://rivya.ai/api/v1/chat/completions/stream \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -H "Idempotency-Key: chat-stream-001" \
  -d '{
    "model": "claude-sonnet-5-chat",
    "message": "Write a concise launch plan for a new product image campaign",
    "client_request_id": "chat-stream-001"
  }'

การสตรีม คำตอบ ใช้ Content-Type: text/event-stream; charset=utf-8

เหตุการณ์:

ตัวอย่างสตรีม:

event: session.created
data: {"request_id":"req_...","session_id":"session_id","model":"claude-sonnet-5-chat"}

event: message.delta
data: {"request_id":"req_...","session_id":"session_id","delta":"Draft ","index":0}

event: message.completed
data: {"request_id":"req_...","session_id":"session_id","message":{"id":"assistant_message_id","role":"assistant","content":"Draft ...","created_at":"2026-05-11T00:00:00.000Z"}}

event: usage.completed
data: {"request_id":"req_...","session_id":"session_id","usage":{"input_tokens":1200,"output_tokens":320,"total_tokens":1520},"credits":{"reserved":3,"final":2}}

event: done
data: {"request_id":"req_...","ok":true}

หากเกิดข้อผิดพลาดหลังส่งเหตุการณ์ SSE แรกแล้ว สตรีมจะส่ง event: error แล้วปิด:

event: error
data: {"error":{"code":"internal_error","message":"The request could not be completed.","requestId":"req_..."}}

หากไคลเอนต์ตัดการเชื่อมต่อก่อนเสร็จ Rivya จะหยุดการสร้างสตรีมที่กำลังทำงานเมื่อทำได้ ส่วนข้อความที่ส่งมาไม่ครบจะไม่ถูกบันทึกเป็นข้อความผู้ช่วยสุดท้าย หากเซิร์ฟเวอร์บันทึก message.completed แล้ว สามารถอ่านผลลัพธ์สุดท้ายภายหลังด้วย GET /api/v1/chat/sessions/{sessionId}

สนทนาต่อใน เซสชัน

ใช้ session_id ที่ได้กลับมา:

curl https://rivya.ai/api/v1/chat/completions \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: chat-turn-002" \
  -d '{
    "model": "claude-sonnet-5-chat",
    "session_id": "session_id",
    "message": "Now turn that into a 5-step execution checklist."
  }'

เซสชันต้องเป็นของบัญชี Rivya เดียวกันและสร้างผ่าน Public API โดย Chat API จะไม่คืนข้อมูลหรือสนทนาต่อจากเซสชันที่มีเฉพาะใน Studio

ไฟล์แนบรูปภาพ

ไฟล์แนบในแชตใช้บันทึกจาก Files API ไม่ใช่ URL ภายนอก

1. อัปโหลดรูปภาพด้วย POST /api/v1/files

2. ใช้ id ที่ได้กลับมาเป็น attachments[].file_id

{
  "model": "<image-capable-chat-model-id>",
  "message": "Review this product photo and suggest a cleaner editorial direction.",
  "attachments": [
    {
      "file_id": "file_..."
    }
  ]
}

ไฟล์ต้องเป็นของบัญชีเดียวกัน มี kind: "image" และพร้อมใช้งาน แทนที่ค่าตัวอย่างด้วยโมเดลแชตที่พร้อมใช้และมี chat_capabilities ใน /api/v1/models ระบุว่ารองรับรูปภาพแนบ claude-sonnet-5-chat เป็นตัวอย่างโมเดลข้อความล้วนในส่วนอื่นของหน้านี้ จึงใช้กับคำขอแนบรูปไม่ได้ โมเดลที่ไม่รองรับรูปภาพแนบจะคืนค่า chat_attachment_not_supported

ตัวควบคุมแบบเลือกใช้

{
  "model": "claude-sonnet-5-chat",
  "message": "Compare three launch options.",
  "enable_web_search": false,
  "reasoning_effort": "default",
  "thought_mode": "default"
}

ตัวควบคุมที่รองรับแตกต่างกันตามโมเดล อ่าน /api/v1/models และตรวจ chat_capabilities ก่อนเปิดตัวควบคุมใน UI

ดูรายการ เซสชัน

ใช้ GET /api/v1/chat/sessions ด้วย คีย์ ที่มี chat:read

curl https://rivya.ai/api/v1/chat/sessions \
  -H "Authorization: Bearer rvya_sk_..."

คำขอนี้คืนเฉพาะเซสชันที่สร้างผ่าน API:

{
  "object": "list",
  "data": [
    {
      "id": "session_id",
      "object": "chat.session",
      "model": "claude-sonnet-5-chat",
      "tool_slug": null,
      "title": "Write a concise launch plan...",
      "controls": {
        "enable_web_search": false,
        "reasoning_effort": null,
        "thought_mode": null
      },
      "created_at": "2026-05-11T00:00:00.000Z",
      "updated_at": "2026-05-11T00:00:00.000Z",
      "last_message_at": "2026-05-11T00:00:00.000Z"
    }
  ]
}

อ่าน เซสชัน เดี่ยว

ใช้ GET /api/v1/chat/sessions/{sessionId} เพื่ออ่านเซสชันที่สร้างผ่าน API หนึ่งรายการและข้อความที่บันทึกแล้วในเซสชันนั้น

curl https://rivya.ai/api/v1/chat/sessions/session_id \
  -H "Authorization: Bearer rvya_sk_..."

คำตอบมีข้อความผู้ใช้และผู้ช่วยที่บันทึกแล้ว โดยไม่เปิดเผยฟิลด์ภายในของผู้ให้บริการ

Idempotency สำหรับป้องกันคำขอซ้ำ

ใช้ Idempotency-Key สำหรับคำขอ การผลิต ทุกครั้งที่เรียก POST /api/v1/chat/completions และ POST /api/v1/chat/completions/stream

หากลองใหม่ด้วยคีย์และเนื้อหาคำขอเดิม Rivya สามารถคืนคำตอบที่บันทึกไว้โดยไม่สร้างข้อความหรือใช้เครดิตซ้ำ หากใช้คีย์เดิมกับข้อมูลนำเข้าต่างกัน API จะคืน idempotency_conflict

สำหรับการลองสตรีมใหม่ Rivya จะไม่ส่งส่วนโทเคนในอดีตซ้ำ การเรียกคำขอที่เสร็จแล้วซ้ำจะคืนลำดับ SSE ขั้นต่ำ ได้แก่ session.created, message.completed, usage.completed และ done

ข้อผิดพลาดที่พบบ่อย

หน้าที่เกี่ยวข้อง

• โมเดล API

• ไฟล์ API

• เครดิต API

• ข้อผิดพลาดและขีดจำกัด API

• สัญญาและโครงสร้าง OpenAPI