non-streaming 또는 SSE turn, API가 만든 session, file_id 이미지 첨부, token 기반 크레딧 정산에 Rivya Chat API를 사용하세요.

완전한 non-streaming chat response 한 번에는 POST /api/v1/chat/completions를 사용하고, Server-Sent Events에는 POST /api/v1/chat/completions/stream을 사용하세요.

Chat API는 session 기반입니다. 새 API chat session을 시작하려면 session_id를 생략하세요. 같은 API 생성 session을 이어가려면 반환된 session_id를 전달하세요.

현재 범위

Chat API v1은 다음을 지원합니다.

non-streaming assistant responses
text/event-stream을 사용하는 SSE streaming
API가 만든 chat sessions
계정 크레딧 예약과 최종 token 기반 정산
선택한 모델이 지원하는 경우 선택적 web search, reasoning effort, thought mode
Files API file_id 값을 통한 이미지 첨부

Chat API v1은 다음을 지원하지 않습니다.

사용자가 제공하는 raw messages history
Studio 전용 chat sessions 이어가기
임의의 외부 첨부 URL
Chat webhook events

필요한 Scope

다음 scope가 있는 API key를 사용하세요.

chat:create
chat:read

Settings에서 새로 만든 key에는 두 scope가 기본으로 포함됩니다. 더 오래된 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"
  }'

Response:

{
  "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 Stream 하기

서버가 assistant delta를 도착하는 대로 받으려면 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": "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	Meaning
`session.created`	API key, model, session, attachments, rate limit, credit reservation checks를 통과했습니다.
`message.delta`	assistant message의 표시용 delta입니다. 아직 commit된 message는 아닙니다.
`message.completed`	assistant message가 API 생성 session에 commit되었습니다.
`usage.completed`	Token usage와 final credits가 정산되었습니다.
`heartbeat`	긴 pause 동안의 keepalive event입니다.
`error`	streaming 시작 후 실패했을 때의 Public API error envelope입니다.
`done`	stream이 성공적으로 완료되었습니다.

Example 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}

첫 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로 저장되지 않습니다. 서버가 이미 message.completed를 commit했다면 최종 결과는 나중에 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가 만든 것이어야 합니다. Studio 전용 chat sessions는 Chat API가 반환하거나 이어가지 않습니다.

이미지 첨부

Chat 첨부는 외부 URL이 아니라 Files API records를 사용합니다.

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"
}

제어 지원은 모델마다 다릅니다. UI에 제어 항목을 노출하기 전에 /api/v1/models를 읽고 chat_capabilities를 확인하세요.

Sessions 목록

chat:read가 포함된 key로 GET /api/v1/chat/sessions를 사용하세요.

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

이 API는 API가 만든 sessions만 반환합니다.

{
  "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 가져오기

API가 만든 session 하나와 commit된 messages를 읽으려면 GET /api/v1/chat/sessions/{sessionId}를 사용하세요.

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

Response에는 commit된 user 및 assistant messages가 포함됩니다. 내부 provider fields는 노출하지 않습니다.

Idempotency

모든 production POST /api/v1/chat/completions 및 POST /api/v1/chat/completions/stream 요청에는 Idempotency-Key를 사용하세요.

retry가 같은 key와 같은 body를 사용하면 Rivya는 다른 message를 만들거나 credits를 다시 소비하지 않고 저장된 response를 반환할 수 있습니다. 같은 key를 다른 input과 함께 재사용하면 API는 idempotency_conflict를 반환합니다.

streaming retry에서 Rivya는 historical token deltas를 replay하지 않습니다. 완료된 replay는 session.created, message.completed, usage.completed, done이 포함된 최소 SSE sequence를 반환합니다.

일반 오류

Code	Meaning
`chat_model_not_supported`	선택한 model은 Chat API에서 사용할 수 없습니다.
`chat_session_conflict`	이 session은 해당 request에 사용할 수 없습니다.
`chat_attachment_not_supported`	attachment가 없거나, account 소유가 아니거나, image가 아니거나, model이 지원하지 않습니다.
`insufficient_credits`	account에 해당 turn을 위한 충분한 credits가 없습니다.
`idempotency_conflict`	idempotency key가 다른 input과 함께 재사용되었습니다.

Chat API