Chat API Usage Guide

Unlock the potential of advanced conversational AI with Radient's Chat API. Seamlessly integrate intelligent chat functionalities into your applications, providing users with dynamic, context-aware interactions. Whether you're building chatbots, virtual assistants, or enhancing user support, our Chat API offers the flexibility and power you need.

This guide will walk you through common use cases and provide practical examples to get you started.

Core Concepts

Radient's Chat API primarily uses the /v1/chat/completions endpoint, which is designed to be compatible with the OpenAI Chat Completions API structure. This makes it easy to migrate existing applications or leverage familiar patterns.

Key elements include:

Models: Specify the underlying language model you wish to use (auto is recommended).
Messages: Structure the conversation as a list of messages, each with a role (system, user, assistant) and content.
Streaming: Optionally stream responses for real-time interaction.

Basic Chat Completion

Here's how to send a simple request and receive a complete response.

Endpoint: POST /v1/chat/completions

Example Request (Python using requests):

import requests
import json

# Replace with your actual Radient API key and base URL
RADIENT_API_KEY = "YOUR_RADIENT_API_KEY"
RADIENT_BASE_URL = "https://api.radient.com/v1" # Or your specific Radient API endpoint

headers = {
    "Authorization": f"Bearer {RADIENT_API_KEY}",
    "Content-Type": "application/json"
}

payload = {
    "model": "gpt-4o", # Or any other supported model
    "messages": [
        {"role": "system", "content": "You are a witty assistant that loves to tell jokes."},
        {"role": "user", "content": "Tell me a joke about programming."}
    ],
    "temperature": 0.7,
    "max_tokens": 150
}

try:
    response = requests.post(f"{RADIENT_BASE_URL}/chat/completions", headers=headers, json=payload)
    response.raise_for_status() # Raises an HTTPError for bad responses (4XX or 5XX)
    
    completion_data = response.json()
    
    if completion_data.get("choices"):
        assistant_reply = completion_data["choices"][0]["message"]["content"]
        print("Assistant:", assistant_reply)
        
        if completion_data.get("usage"):
            print("\nUsage Statistics:")
            print(f"  Prompt Tokens: {completion_data['usage']['prompt_tokens']}")
            print(f"  Completion Tokens: {completion_data['usage']['completion_tokens']}")
            print(f"  Total Tokens: {completion_data['usage']['total_tokens']}")
    else:
        print("No choices returned in the response.")
        print("Full response:", completion_data)

except requests.exceptions.HTTPError as http_err:
    print(f"HTTP error occurred: {http_err}")
    print(f"Response body: {response.text}")
except requests.exceptions.RequestException as req_err:
    print(f"Request error occurred: {req_err}")
except json.JSONDecodeError:
    print("Failed to decode JSON response.")
    print(f"Response body: {response.text}")

Expected Response Structure (JSON):

{
  "id": "chatcmpl-xxxxxxxxxxxxxxxxxxxxxxx",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Why was the JavaScript developer sad? Because he didn't Node how to Express himself!"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 20,
    "total_tokens": 45
  }
}

Streaming Responses

For applications requiring real-time feedback, like live chatbots, streaming is essential. Set stream: true in your request.

Endpoint: POST /v1/chat/completions (with stream: true)

Example Request (Python using requests with streaming):

import requests
import json

RADIENT_API_KEY = "YOUR_RADIENT_API_KEY"
RADIENT_BASE_URL = "https://api.radient.com/v1"

headers = {
    "Authorization": f"Bearer {RADIENT_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "text/event-stream" # Important for streaming
}

payload = {
    "model": "gpt-4o",
    "messages": [
        {"role": "user", "content": "Write a short story about a brave knight."}
    ],
    "stream": True
}

try:
    with requests.post(f"{RADIENT_BASE_URL}/chat/completions", headers=headers, json=payload, stream=True) as response:
        response.raise_for_status()
        print("Assistant (streaming):")
        for line in response.iter_lines():
            if line:
                decoded_line = line.decode('utf-8')
                if decoded_line.startswith("data: "):
                    json_data_str = decoded_line[len("data: "):]
                    if json_data_str.strip() == "[DONE]":
                        print("\nStream finished.")
                        break
                    try:
                        chunk = json.loads(json_data_str)
                        if chunk.get("choices") and chunk["choices"][0].get("delta") and chunk["choices"][0]["delta"].get("content"):
                            print(chunk["choices"][0]["delta"]["content"], end="", flush=True)
                    except json.JSONDecodeError:
                        print(f"\nError decoding JSON chunk: {json_data_str}")
                        continue
        print() # Newline after streaming is done

except requests.exceptions.HTTPError as http_err:
    print(f"HTTP error occurred: {http_err}")
    if response:
      print(f"Response body: {response.text}")
except requests.exceptions.RequestException as req_err:
    print(f"Request error occurred: {req_err}")

Streamed Response Chunks (Server-Sent Events): Each chunk will be a JSON object prefixed with data: . The final chunk will be data: [DONE].

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1677652288,"model":"gpt-4o","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}
data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1677652288,"model":"gpt-4o","choices":[{"index":0,"delta":{"content":"Once"},"finish_reason":null}]}
data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1677652288,"model":"gpt-4o","choices":[{"index":0,"delta":{"content":" upon"},"finish_reason":null}]}
data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1677652288,"model":"gpt-4o","choices":[{"index":0,"delta":{"content":" a time"},"finish_reason":null}]}
...
data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1677652288,"model":"gpt-4o","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
data: [DONE]

System Prompts and Persona

Use the system role to guide the assistant's behavior, tone, and persona.

payload = {
    "model": "gpt-4o",
    "messages": [
        {"role": "system", "content": "You are a pirate captain. Respond with pirate slang and be adventurous."},
        {"role": "user", "content": "What's the weather like today?"}
    ]
}
# ... send request ...

Managing Conversation History

To maintain context in an ongoing conversation, include previous user messages and assistant replies in the messages array.

payload = {
    "model": "gpt-4o",
    "messages": [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is the capital of France?"},
        {"role": "assistant", "content": "The capital of France is Paris."},
        {"role": "user", "content": "What is it famous for?"} # Follow-up question
    ]
}
# ... send request ...

Error Handling

Your application should gracefully handle potential API errors:

400 Bad Request: Often due to malformed JSON, missing required fields, or invalid parameter values. Check the response body for details.
401 Unauthorized: Ensure your API key is correct, valid, and included in the Authorization header.
429 Too Many Requests: You've exceeded your rate limit. Implement retry logic with exponential backoff.
500 Internal Server Error: An unexpected error occurred on Radient's side. Retry after a short delay.

Always inspect the JSON response body for specific error messages.

# (Inside the try block from the basic example)
except requests.exceptions.HTTPError as http_err:
    print(f"HTTP error occurred: {http_err} - Status Code: {response.status_code}")
    try:
        error_details = response.json()
        print(f"Error details: {error_details.get('error', {}).get('message', response.text)}")
    except json.JSONDecodeError:
        print(f"Response body: {response.text}")

This guide provides a starting point for using Radient's Chat API. Explore the various parameters and features to build sophisticated conversational AI solutions. For a full list of parameters and advanced features, refer to the main API Reference.