Chat API

Brug POST /api/v1/chat/completions til ét komplet chatsvar uden streaming, eller POST /api/v1/chat/completions/stream til Server-Sent Events.

Chat API er sessionsbaseret. Udelad session_id for at starte en ny API-chat-session. Send et returneret session_id for at fortsætte den samme API-oprettede session.

Denne side dokumenterer den implementerede Public API v1-kontrakt. Adgang under kørsel kræver stadig, at Public API er aktiveret for installationen, at kontoen har en aktiv API-nøgle, og at den valgte model rapporterer en tilgængelig API-status. Tjek den aktive modelliste, før du sender en produktionsanmodning.

Aktuelt omfang

Chat API v1 understøtter:

• komplette assistentsvar uden streaming

• SSE-streaming med text/event-stream

• API-oprettede chat-sessioner

• reservation af kontokreditter og endelig tokenbaseret afregning

• valgfri websøgning, ræsonneringsniveau og tanketilstand, når den valgte model understøtter det

• billedvedhæftninger via file_id-værdier fra Fil-API-et

Chat API v1 understøtter ikke:

• brugerleveret rå messages-historik

• fortsættelse af chatsessioner, der kun findes i Studio

• vilkårlige eksterne URL'er til vedhæftninger

• webhookhændelser for chat

Påkrævede scopes

Brug en API-nøgle med:

chat:create
chat:read

Nye nøgler, der oprettes under Indstillinger, omfatter som standard begge adgangsområder. Ældre nøgler skal muligvis oprettes igen, før Chat API kan kaldes.

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

Stream en chat completion

Brug POST /api/v1/chat/completions/stream, når din server skal modtage ændringer i assistentens svar, efterhånden som de ankommer:

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

Streaming-svar bruger Content-Type: text/event-stream; charset=utf-8.

Events:

Eksempel på stream:

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}

Hvis der sker en fejl efter den første SSE-event, sender streamen event: error og lukker derefter:

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

Hvis klienten afbryder før completion, stopper Rivya den igangværende generation stream, når det er muligt. Delvise deltas gemmes ikke som en endelig assistant-besked. Hvis serveren allerede har committed message.completed, kan det endelige resultat læses senere med GET /api/v1/chat/sessions/{sessionId}.

Fortsæt en session

Brug det returnerede 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 skal tilhøre den samme Rivya-konto og skal være oprettet af Public API. Studio-only chat-sessioner returneres eller fortsættes ikke af Chat API.

Billedvedhæftninger

Chatvedhæftninger bruger poster fra Fil-API-et, ikke eksterne URL'er.

1. Upload et billede med POST /api/v1/files.

2. Brug det returnerede 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 skal tilhøre samme konto, have kind: "image" og være tilgængelig. Erstat pladsholderen med en aktuelt tilgængelig chatmodel, hvis post i /api/v1/models rapporterer understøttelse af billedvedhæftninger i chat_capabilities. claude-sonnet-5-chat er teksteksemplet, der bruges andre steder på siden, og må ikke bruges til denne vedhæftningsanmodning. Modeller uden understøttelse af billedvedhæftninger returnerer chat_attachment_not_supported.

Valgfrie kontroller

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

Kontrolunderstøttelse varierer efter model. Læs /api/v1/models, og kontroller chat_capabilities, før du viser kontroller i din UI.

List sessioner

Brug GET /api/v1/chat/sessions med en nøgle, der inkluderer chat:read.

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

Dette returnerer kun API-oprettede 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"
    }
  ]
}

Hent en session

Brug GET /api/v1/chat/sessions/{sessionId} til at læse én API-oprettet session og dens committed beskeder.

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

Svaret indeholder gemte bruger- og assistentbeskeder. Det viser ikke interne leverandørfelter.

Idempotency

Brug Idempotency-Key til hver produktionsanmodning til POST /api/v1/chat/completions og POST /api/v1/chat/completions/stream.

Hvis et nyt forsøg bruger samme nøgle og samme anmodningskrop, kan Rivya returnere det gemte svar uden at oprette en ny besked eller bruge kreditter igen. Hvis den samme nøgle genbruges med andet indhold, returnerer API-et idempotency_conflict.

Ved gentagne forsøg med streaming afspiller Rivya ikke tidligere tokenændringer. Et genafspillet, afsluttet svar returnerer en minimal SSE-sekvens med session.created, message.completed, usage.completed og done.

Almindelige fejl

Relaterede sider

• API-modeller

• Fil-API

• API-kreditter

• API-fejl og grænser

• OpenAPI- og schema-kontrakt