Skip to main content

​
Overview

The Chat Completions API generates AI responses for conversations, enhanced with Mavera’s persona intelligence. It’s fully compatible with OpenAI SDKs — just change the base URL and add a persona_id.

​
Key Features

Persona Intelligence

Inject specialized personas to get audience-aware responses

OpenAI Compatible

Works with any OpenAI SDK out of the box

Streaming Support

Real-time streaming via Server-Sent Events

Analysis Mode

Get structured insights with confidence scores

​
Basic Usage

from openai import OpenAI

client = OpenAI(
    api_key="mvra_live_your_key_here",
    base_url="https://app.mavera.io/api/v1",
)

response = client.chat.completions.create(
    model="mavera-1",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "How do Gen Z consumers view sustainability?"}
    ],
    extra_body={"persona_id": "YOUR_PERSONA_ID"},
)

print(response.choices[0].message.content)

​
Streaming

Enable real-time streaming for better UX: 
stream = client.chat.completions.create(
    model="mavera-1",
    messages=[{"role": "user", "content": "Write a product description"}],
    extra_body={"persona_id": "YOUR_PERSONA_ID"},
    stream=True,
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

​
Analysis Mode

Enable analysis mode for structured insights: 
response = client.chat.completions.create(
    model="mavera-1",
    messages=[
        {"role": "user", "content": "How do millennials feel about remote work?"}
    ],
    extra_body={
        "persona_id": "YOUR_PERSONA_ID",
        "analysis_mode": True,
    },
)

# Access structured analysis
analysis = response.analysis
print(f"Confidence: {analysis['confidence']}/10")
print(f"Emotional valence: {analysis['emotion']['emotional_valence']}/10")
print(f"Biases detected: {[b['name'] for b in analysis['biases']]}")
Analysis mode returns:
  • Confidence score (1-10)
  • Emotional analysis (valence, arousal, dominance)
  • Bias detection (cognitive biases that may affect the response)
  • Key insights (structured takeaways)

​
Image Attachments

Include images for visual analysis: 
curl -X POST https://app.mavera.io/api/v1/chat/completions \
  -H "Authorization: Bearer mvra_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mavera-1",
    "persona_id": "YOUR_PERSONA_ID",
    "messages": [
      {
        "role": "user",
        "content": "What is in this image?",
        "attachments": [
          { "type": "image", "url": "https://your-bucket.s3.amazonaws.com/image.png" }
        ]
      }
    ]
  }'

​
Advanced Options

ParameterTypeDescription
persona_idstringID of the persona to use
analysis_modebooleanEnable structured analysis output
reasoning_effortstring"low", "medium", or "high"
verbositystring"low", "medium", or "high"
streambooleanEnable streaming responses
temperaturenumberRandomness (0-2, default 1)
max_tokensintegerMaximum tokens in response

​
Response Format

{
  "id": "chatcmpl_abc123def456",
  "object": "chat.completion",
  "created": 1706345678,
  "model": "mavera-1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Based on my understanding as a Gen Z consumer..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "credits_used": 3,
    "prompt_tokens": 150,
    "completion_tokens": 200,
    "total_tokens": 350
  }
}

​
Best Practices

Select personas that match your target audience. A Gen Z persona will respond differently than a B2B Executive persona.
Combine persona intelligence with specific system prompts for best results.
Use streaming for long responses to improve perceived latency.
Check usage.credits_used in responses to track costs.

API Reference

See the full API specification