Migrate OpenAI to Mavera

Switch from OpenAI to Mavera with minimal code changes — base URL, persona_id, and SDK compatibility

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

Feature	OpenAI	Mavera	Notes
Input format	input: [{role, content}]	Same	No change
Streaming	client.responses.stream()	Same	SSE, same event types
Model parameter	model="gpt-4"	model="mavera-1"	Use mavera-1
Tools / function calling	tools, tool_choice	Same	No change
Structured outputs	text.format	Same	json_object, json_schema
Temperature, max_tokens	Same	Same	No change
Instructions parameter	Same	Same	No change

---

What Changes

Item	Change
Base URL	https://app.mavera.io/api/v1
API key	Mavera key (starts with mvra_live_)
Model	mavera-1
Persona	Add persona_id (required for best results)
Optional fields	analysis_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

.env

# 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

# Or keep both during transition
OPENAI_API_KEY=sk-xxx
MAVERA_API_KEY=mvra_live_xxx

4. Change Client Configuration

Python

# 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",
)

// Before (OpenAI)
import OpenAI from "openai";
const client = new OpenAI();

// After (Mavera)
import OpenAI from "openai";
const client = new OpenAI({
  apiKey: process.env.MAVERA_API_KEY,
  baseURL: "https://app.mavera.io/api/v1",
});

// Before (OpenAI)
config := openai.DefaultConfig(os.Getenv("OPENAI_API_KEY"))
client := openai.NewClientWithConfig(config)

// After (Mavera)
config := openai.DefaultConfig(os.Getenv("MAVERA_API_KEY"))
config.BaseURL = "https://app.mavera.io/api/v1"
client := openai.NewClientWithConfig(config)

5. Add persona_id to Requests

Python

# 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"},
)

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

// After (Mavera) — JavaScript accepts persona_id directly
const response = await client.responses.create({
  model: "mavera-1",
  input: [{ role: "user", content: "Hello" }],
  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

Field	Type	Description	Python	JavaScript
persona_id	string	Required for best results. Persona to use	extra_body={"persona_id": "..."}	persona_id: "..."
analysis_mode	boolean	Return structured analysis (confidence, biases, etc.)	extra_body={"analysis_mode": True}	analysis_mode: true
reasoning_effort	string	"low", "medium", "high"	extra_body={"reasoning_effort": "high"}	reasoning_effort: "high"
verbosity	string	Response length preference	extra_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.

Python

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": [...]},
)

const headers = { Authorization: `Bearer ${process.env.MAVERA_API_KEY}` };
const base = "https://app.mavera.io/api/v1";

const maveResp = await fetch(`${base}/mave/chat`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({ message: "Analyze the EV market in Europe" }),
});

---

Migration Checklist

Pre-migration

• 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

Code changes

• 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)

Environment & config

• Add MAVERA_API_KEY to env (or repoint OPENAI_API_KEY)
• Update any config files or secrets managers

Testing

• 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

Production

• Deploy behind feature flag or canary if possible
• Monitor Credits and Rate Limits
• Set up Error Handling for 401, 402, 429

---

Common Gotchas

Python: persona_id not applied

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

TypeScript: persona_id type errors

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.

Credits vs tokens

Mavera uses credits, not token-based pricing. Each response includes usage.credits_used. See Credits.

Different rate limits

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