Skip to main content

​
When to Use This

You’re already using the OpenAI Python or JavaScript SDK and want to switch to Mavera with:
  • Minimal code changes (often 2–3 lines)
  • Preserved behavior for input, streaming, tools, and structured outputs
  • New capabilities (personas, analysis mode) injected via extra parameters
Mavera’s API is OpenAI-compatible: same SDK interface, same Responses API. You change the base URL, add persona_id, and optionally use Mavera-specific fields like analysis_mode.

​
What Stays the Same

FeatureOpenAIMaveraNotes
Input formatinput: [{role, content}]SameNo change
Streamingclient.responses.stream()SameSSE, same event types
Model parametermodel="gpt-4"model="mavera-1"Use mavera-1
Tools / function callingtools, tool_choiceSameNo change
Structured outputstext.formatSamejson_object, json_schema
Temperature, max_tokensSameSameNo change
Instructions parameterSameSameNo change

​
What Changes

ItemChange
Base URLhttps://app.mavera.io/api/v1
API keyMavera key (starts with mvra_live_)
Modelmavera-1
PersonaAdd persona_id (required for best results)
Optional fieldsanalysis_mode, reasoning_effort, etc. (see Responses API)

​
Step-by-Step Migration

​
1. Get a Mavera API Key

Create an API key at app.mavera.io/settings/developer. Keys start with mvra_live_.

​
2. Get a Persona ID

Every Mavera request should include a persona_id for audience-aware responses. List personas and pick one: 
curl -s https://app.mavera.io/api/v1/personas -H "Authorization: Bearer mvra_live_YOUR_KEY" | jq '.data[:3] | .[] | {name, id}'

​
3. Update Environment Variables

# Before (OpenAI)
OPENAI_API_KEY=sk-xxx

# After (Mavera)
MAVERA_API_KEY=mvra_live_xxx
OPENAI_API_KEY=mvra_live_xxx   # Optional: reuse same var if your code reads OPENAI_API_KEY

​
4. Change Client Configuration

# Before (OpenAI)
from openai import OpenAI
client = OpenAI()  # Uses OPENAI_API_KEY, default base URL

# After (Mavera)
from openai import OpenAI
client = OpenAI(
    api_key="mvra_live_your_key_here",
    base_url="https://app.mavera.io/api/v1",
)
# Or with env:
import os
client = OpenAI(
    api_key=os.environ.get("MAVERA_API_KEY"),
    base_url="https://app.mavera.io/api/v1",
)

​
5. Add persona_id to Requests

# Before (OpenAI)
response = client.responses.create(
    model="gpt-4",
    input=[{"role": "user", "content": "Hello"}],
)

# After (Mavera) — Python requires extra_body for non-OpenAI fields
response = client.responses.create(
    model="mavera-1",
    input=[{"role": "user", "content": "Hello"}],
    extra_body={"persona_id": "clx1abc2d0001abcdef123456"},
)
Python quirk: The OpenAI Python SDK’s type definitions don’t include persona_id, so you must pass it via extra_body. The SDK forwards unknown kwargs to the API. JavaScript/TypeScript: You can add persona_id (and other Mavera fields) directly to the request object.

​
Mavera-Specific Fields Reference

FieldTypeDescriptionPythonJavaScript
persona_idstringRequired for best results. Persona to useextra_body={"persona_id": "..."}persona_id: "..."
analysis_modebooleanReturn structured analysis (confidence, biases, etc.)extra_body={"analysis_mode": True}analysis_mode: true
reasoning_effortstring"low", "medium", "high"extra_body={"reasoning_effort": "high"}reasoning_effort: "high"
verbositystringResponse length preferenceextra_body={"verbosity": "medium"}verbosity: "medium"

​
Non-Chat Endpoints: Use REST

Mavera has non-OpenAI endpoints (Mave Agent, Focus Groups, Video Analysis, etc.) that don’t use the OpenAI SDK. Call them directly with fetch, requests, or httpx. 
import requests

headers = {"Authorization": f"Bearer {os.environ['MAVERA_API_KEY']}"}
base = "https://app.mavera.io/api/v1"

# Mave Agent
resp = requests.post(
    f"{base}/mave/chat",
    headers=headers,
    json={"message": "Analyze the EV market in Europe"},
)

# Focus Groups
resp = requests.post(
    f"{base}/focus-groups",
    headers=headers,
    json={"name": "My FG", "sample_size": 50, "persona_ids": [...], "workspace_id": "ws_xxx", "questions": [...]},
)

​
Migration Checklist

  • Create Mavera account and API key
  • List personas and pick a default persona_id
  • Note your current model usage (e.g. gpt-4) — Mavera uses mavera-1
  • Set base_url / baseURL to https://app.mavera.io/api/v1
  • Set api_key / apiKey to Mavera key
  • Replace model name with mavera-1
  • Add persona_id to all response calls (Python: extra_body, JS: direct)
  • Add MAVERA_API_KEY to env (or repoint OPENAI_API_KEY)
  • Update any config files or secrets managers
  • Run a simple response (no streaming)
  • Run a streaming response
  • Test tools/function calling if used
  • Test structured outputs if used
  • Verify usage.credits_used in responses

​
Common Gotchas

You must pass persona_id in extra_body, not as a top-level kwarg. client.responses.create(..., persona_id="x") will not work — use extra_body={"persona_id": "x"}.
The OpenAI types don’t include persona_id. Use as any or extend the types, or pass via a wrapper that adds Mavera fields before the SDK call.
Mavera uses credits, not token-based pricing. Each response includes usage.credits_used. See Credits.
Mavera rate limits differ by tier. See Rate Limits. If you were batching heavily on OpenAI, you may need to throttle.

​
See Also

Quickstart: Chat

First Mavera request with persona

SDKs Overview

Python, JavaScript, Go, and REST usage

Responses API

Full feature set: streaming, tools, analysis mode

Persona Selection

How to choose the right persona