ใช้ Rivya Chat API สำหรับ turn แบบ non-streaming หรือ SSE, session ที่สร้างผ่าน API, ไฟล์แนบรูปภาพแบบ file_id และการคิดเครดิตตาม token

ใช้ POST /api/v1/chat/completions สำหรับคำตอบแชตแบบ non-streaming ที่สมบูรณ์หนึ่งรอบ หรือใช้ POST /api/v1/chat/completions/stream สำหรับ Server-Sent Events

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

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

Chat API v1 รองรับ:

คำตอบ assistant แบบ non-streaming
SSE streaming ด้วย text/event-stream
chat session ที่สร้างผ่าน API
การกันเครดิตบัญชีล่วงหน้าและการสรุปยอดสุดท้ายตาม token
web search, reasoning effort และ thought mode แบบเลือกใช้ได้เมื่อโมเดลที่เลือกสนับสนุน
ไฟล์แนบรูปภาพผ่านค่า file_id ของ Files API

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

ประวัติ raw messages ที่ผู้ใช้ส่งเอง
การสนทนาต่อจาก chat session ที่มีเฉพาะใน Studio
URL ไฟล์แนบภายนอกตามอำเภอใจ
เหตุการณ์ webhook ของ Chat

Scopes ที่จำเป็น

ใช้ API key ที่มี:

chat:create
chat:read

key ใหม่ที่สร้างใน Settings จะมี scopes ทั้งสองนี้ตามค่าเริ่มต้น key รุ่นเก่าอาจต้องสร้างใหม่ก่อนเรียกใช้ Chat API

สร้าง Chat Completion

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": "gpt-5-2-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": "gpt-5-2-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
  }
}

สตรีม Chat Completion

ใช้ POST /api/v1/chat/completions/stream เมื่อ server ของคุณต้องการรับ assistant deltas ทันทีที่ส่งมา:

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": "gpt-5-2-chat",
    "message": "Write a concise launch plan for a new product image campaign",
    "client_request_id": "chat-stream-001"
  }'

Streaming responses ใช้ Content-Type: text/event-stream; charset=utf-8

Events:

Event	ความหมาย
`session.created`	API key, model, session, attachments, rate limit และการกันเครดิตผ่านการตรวจสอบแล้ว
`message.delta`	delta สำหรับแสดงผลใน assistant message ยังไม่ใช่ข้อความที่ commit แล้ว
`message.completed`	assistant message ถูก commit เข้าสู่ session ที่สร้างผ่าน API แล้ว
`usage.completed`	สรุป token usage และเครดิตสุดท้ายแล้ว
`heartbeat`	keepalive event ระหว่างช่วงพักยาว
`error`	public API error envelope สำหรับความล้มเหลวหลังเริ่ม streaming แล้ว
`done`	stream เสร็จสมบูรณ์แล้ว

ตัวอย่าง stream:

event: session.created
data: {"request_id":"req_...","session_id":"session_id","model":"gpt-5-2-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}

หากเกิด error หลังส่ง SSE event แรกแล้ว stream จะส่ง event: error แล้วปิด:

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

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

สนทนาต่อใน Session

ใช้ 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": "gpt-5-2-chat",
    "session_id": "session_id",
    "message": "Now turn that into a 5-step execution checklist."
  }'

session ต้องเป็นของบัญชี Rivya เดียวกัน และต้องถูกสร้างโดย Public API Chat API จะไม่คืนหรือสนทนาต่อจาก Studio-only chat sessions

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

ไฟล์แนบ Chat ใช้ records ของ Files API ไม่ใช่ URL ภายนอก

อัปโหลดรูปภาพด้วย POST /api/v1/files
ใช้ id ที่ได้กลับมาเป็น attachments[].file_id

{
  "model": "gpt-5-2-chat",
  "message": "Review this product photo and suggest a cleaner editorial direction.",
  "attachments": [
    {
      "file_id": "file_..."
    }
  ]
}

ไฟล์ต้องเป็นของบัญชีเดียวกัน มี kind: "image" และพร้อมใช้งาน โมเดลที่ไม่รองรับไฟล์แนบรูปภาพจะคืนค่า chat_attachment_not_supported

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

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

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

ดูรายการ Sessions

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

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

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

{
  "object": "list",
  "data": [
    {
      "id": "session_id",
      "object": "chat.session",
      "model": "gpt-5-2-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"
    }
  ]
}

อ่าน Session เดี่ยว

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

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

response มี user และ assistant messages ที่ commit แล้ว และไม่เปิดเผย fields ภายในของ provider

Idempotency เพื่อป้องกันคำขอซ้ำ

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

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

สำหรับ streaming retries Rivya จะไม่ replay token deltas ในอดีต replay ของคำขอที่เสร็จแล้วจะคืนลำดับ SSE ขั้นต่ำพร้อม session.created, message.completed, usage.completed และ done

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

Code	ความหมาย
`chat_model_not_supported`	โมเดลที่เลือกยังไม่พร้อมใช้งานกับ Chat API
`chat_session_conflict`	session นี้ใช้กับคำขอนี้ไม่ได้
`chat_attachment_not_supported`	ไฟล์แนบหายไป ไม่ได้เป็นของบัญชี ไม่ใช่รูปภาพ หรือโมเดลไม่รองรับ
`insufficient_credits`	บัญชีมีเครดิตไม่พอสำหรับ turn นี้
`idempotency_conflict`	idempotency key ถูกใช้ซ้ำกับ input ที่ต่างกัน

Chat API ของ Rivya