Chat API

Använd POST /api/v1/chat/completions för ett komplett icke-streamande chattsvar, eller POST /api/v1/chat/completions/stream för Server-Sent Events.

Chat API är sessionsbaserat. Utelämna session_id för att starta en ny API-chattsession. Skicka med ett returnerat session_id för att fortsätta samma API-skapade session.

Sidan dokumenterar det implementerade kontraktet för det offentliga API v1. Körning kräver fortfarande att API:et är aktiverat för driftsmiljön, att kontot har en aktiv API-nyckel och att den valda modellens API-status tillåter anropet. Kontrollera den aktuella modellistan innan du skickar en produktionsbegäran.

Aktuell omfattning

Chat API v1 stöder:

• icke-streamande assistentsvar

• SSE-streaming med text/event-stream

• API-skapade chattsessioner

• reservation av kontokrediter och slutlig tokenbaserad avräkning

• valfri webbsökning, resonemangsnivå och tankeläge när den valda modellen stöder det

• bildbilagor via Files API-värden för file_id

Chat API v1 stöder inte:

• rå messages-historik som användaren skickar in

• fortsättning av Studio-exklusiva chattsessioner

• godtyckliga externa bilage-URL:er

• Webhook-händelser för Chat

Nödvändiga scopes

Använd en API-nyckel med:

chat:create
chat:read

Nya nycklar som skapas i Settings innehåller båda scopes som standard. Äldre nycklar kan behöva skapas om innan Chat API anropas.

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

Svar:

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

Streama en chat completion

Använd POST /api/v1/chat/completions/stream när din server vill ta emot assistant-deltan medan de kommer:

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

Streamande svar använder Content-Type: text/event-stream; charset=utf-8.

Händelser:

Exempelstream:

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}

Om ett fel inträffar efter den första SSE-händelsen skickar streamen event: error och stängs sedan:

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

Om klienten kopplar från innan slutförande stoppar Rivya den pågående genereringsstreamen när det är möjligt. Partiella deltan sparas inte som ett slutligt assistentmeddelande. Om servern redan har committat message.completed kan slutresultatet läsas senare med GET /api/v1/chat/sessions/{sessionId}.

Fortsätt en session

Använd det returnerade 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."
  }'

Sessionen måste tillhöra samma Rivya-konto och ha skapats av det offentliga API:et. Chattsessioner som bara finns i Studio returneras eller fortsätts inte av Chat API.

Bildbilagor

Chatbilagor använder Files API-poster, inte externa URL:er.

1. Ladda upp en bild med POST /api/v1/files.

2. Använd det returnerade id som attachments[].file_id.

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

Filen måste tillhöra samma konto, ha kind: "image" och vara tillgänglig. Ersätt platshållaren med en för närvarande tillgänglig chattmodell vars post i /api/v1/models anger stöd för bildbilagor i chat_capabilities. claude-sonnet-5-chat är det textbaserade exemplet på resten av sidan och får inte användas för denna begäran med bilaga. Modeller som inte stöder bildbilagor returnerar chat_attachment_not_supported.

Valfria kontroller

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

Kontrollstöd varierar per modell. Läs /api/v1/models och kontrollera chat_capabilities innan du visar kontroller i ditt UI.

Lista sessioner

Använd GET /api/v1/chat/sessions med en nyckel som innehåller chat:read.

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

Detta returnerar endast API-skapade sessioner:

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

Hämta en session

Använd GET /api/v1/chat/sessions/{sessionId} för att läsa en API-skapad session och dess committade meddelanden.

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

Svaret innehåller committade användar- och assistentmeddelanden. Det exponerar inte interna leverantörs-fält.

Idempotens

Använd Idempotency-Key för varje produktionsanrop till POST /api/v1/chat/completions och POST /api/v1/chat/completions/stream.

Om ett nytt försök använder samma nyckel och samma begärandeinnehåll kan Rivya returnera det sparade svaret utan att skapa ett nytt meddelande eller förbruka fler krediter. Om samma nyckel återanvänds med annan indata returnerar API:et idempotency_conflict.

Vid streaming-retries spelar Rivya inte upp historiska tokendeltan. En slutförd replay returnerar en minimal SSE-sekvens med session.created, message.completed, usage.completed och done.

Vanliga fel

Relaterade sidor

• API-modeller

• Files API

• API-krediter

• API-fel och gränser

• OpenAPI och schemakontrakt