채팅 API

완전한 비스트리밍 채팅 응답 한 번에는 POST /api/v1/chat/completions를 사용하고, 서버 전송 이벤트(SSE)에는 POST /api/v1/chat/completions/stream을 사용하세요.

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

이 페이지는 구현된 Public API v1 계약을 설명합니다. 실제 실행에는 배포에서 Public API가 활성화되어 있고 계정에 유효한 API 키가 있으며 선택한 모델의 실시간 API 상태가 사용 가능해야 합니다. 문서가 존재한다고 모든 환경에서 호출할 수 있는 것은 아닙니다.

현재 범위

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

• 비스트리밍 어시스턴트 응답

• text/event-stream을 사용하는 SSE 스트리밍

• API가 만든 채팅 세션

• 계정 크레딧 예약과 최종 토큰 기반 정산

• 선택한 모델이 지원하는 경우 선택적 웹 검색, 추론 강도, 사고 모드

• Files API file_id 값을 통한 이미지 첨부

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

• 사용자가 제공하는 원시 messages 기록

• Studio 전용 채팅 세션 이어가기

• 임의의 외부 첨부 URL

• Chat 웹훅 이벤트

필요한 범위

다음 범위가 있는 API 키를 사용하세요.

chat:create
chat:read

Settings에서 새로 만든 키에는 두 범위가 기본으로 포함됩니다. 더 오래된 키는 Chat 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가 만든 것이어야 합니다. Studio 전용 채팅 세션은 Chat API가 반환하거나 이어가지 않습니다.

이미지 첨부

Chat 첨부에는 외부 URL이 아니라 Files API 레코드를 사용합니다.

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이며 사용 가능한 상태여야 합니다. 자리표시자는 현재 사용 가능하고 /api/v1/models의 chat_capabilities에서 이미지 첨부 지원이 확인되는 채팅 모델로 바꾸세요. 다른 예제의 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"
}

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

세션 목록

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

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

이 API는 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"
    }
  ]
}

세션 가져오기

API가 만든 세션 하나와 확정된 메시지를 읽으려면 GET /api/v1/chat/sessions/{sessionId}를 사용하세요.

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

응답에는 확정된 사용자 및 어시스턴트 메시지가 포함됩니다. 내부 제공사 필드는 노출하지 않습니다.

멱등성

모든 운영 환경의 POST /api/v1/chat/completions 및 POST /api/v1/chat/completions/stream 요청에는 Idempotency-Key를 사용하세요.

재시도가 같은 키와 같은 본문을 사용하면 Rivya는 다른 메시지를 만들거나 크레딧을 다시 소비하지 않고 저장된 응답을 반환할 수 있습니다. 같은 키를 다른 입력과 함께 재사용하면 API는 idempotency_conflict를 반환합니다.

스트리밍 재시도에서 Rivya는 과거 토큰 응답 조각을 다시 전송하지 않습니다. 완료된 요청을 재생하면 session.created, message.completed, usage.completed, done이 포함된 최소 SSE 순서를 반환합니다.

일반 오류

관련 페이지

• API 모델

• Files API

• API 크레딧

• API 오류와 제한

• OpenAPI와 스키마 계약