Brug Rivya Chat API til ikke-streaming eller SSE-turns, API-oprettede sessioner, file_id-billedvedhæftninger og tokenbaseret credit-afregning.

Brug POST /api/v1/chat/completions til ét komplet ikke-streaming chatsvar, 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.

Aktuelt omfang

Chat API v1 understøtter:

ikke-streaming assistentsvar
SSE-streaming med text/event-stream
API-oprettede chat-sessioner
reservation af konto-credits og endelig tokenbaseret afregning
valgfri web search, reasoning effort og thought mode, når den valgte model understøtter det
billedvedhæftninger via Files API file_id-værdier

Chat API v1 understøtter ikke:

brugerleveret rå messages-historik
fortsættelse af Studio-only chat-sessioner
vilkårlige eksterne URL'er til vedhæftninger
Chat webhook events

Påkrævede scopes

Brug en API-nøgle med:

chat:create
chat:read

Nye nøgler oprettet i Settings inkluderer som standard begge scopes. Æ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": "gpt-5-2-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": "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
  }
}

Stream en chat completion

Brug POST /api/v1/chat/completions/stream, når din server vil modtage assistant-deltas, 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": "gpt-5-2-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:

Event	Betydning
`session.created`	API-nøgle, model, session, vedhæftninger, rate limit og credit-reservation er kontrolleret.
`message.delta`	Et visningsdelta for assistant-beskeden. Det er endnu ikke en committed besked.
`message.completed`	Assistant-beskeden er committed til den API-oprettede session.
`usage.completed`	Tokenforbrug og endelige credits er afregnet.
`heartbeat`	Keepalive-event under lange pauser.
`error`	Offentlig API-fejlkonvolut for en fejl efter streaming er startet.
`done`	Streamen blev gennemført.

Eksempel på 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}

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

Chat-vedhæftninger bruger Files API-records, ikke eksterne URL'er.

Upload et billede med POST /api/v1/files.
Brug det returnerede id som attachments[].file_id.

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

Filen skal tilhøre den samme konto, have kind: "image" og være tilgængelig. Modeller, der ikke understøtter billedvedhæftninger, returnerer chat_attachment_not_supported.

Valgfrie kontroller

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

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 inkluderer committed user- og assistant-beskeder. Det eksponerer ikke interne provider-felter.

Idempotency

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

Hvis et retry bruger samme nøgle og samme body, kan Rivya returnere det gemte svar uden at oprette en ny besked eller forbruge credits igen. Hvis samme nøgle genbruges med et andet input, returnerer API'en idempotency_conflict.

Ved streaming-retries afspiller Rivya ikke historiske token-deltas. En completed replay returnerer en minimal SSE-sekvens med session.created, message.completed, usage.completed og done.

Almindelige fejl

Code	Betydning
`chat_model_not_supported`	Den valgte model er ikke tilgængelig for Chat API.
`chat_session_conflict`	Sessionen kan ikke bruges til denne anmodning.
`chat_attachment_not_supported`	Vedhæftningen mangler, ejes ikke af kontoen, er ikke et billede eller understøttes ikke af modellen.
`insufficient_credits`	Kontoen har ikke credits nok til turnen.
`idempotency_conflict`	Idempotency key blev genbrugt med et andet input.

Chat API