> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mavera.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/features/responses#advanced-options)) |

***

## Step-by-Step Migration

### 1. Get a Mavera API Key

Create an API key at [app.mavera.io/settings/developer](https://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:

```bash theme={"dark"}
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

<CodeGroup>
  ```bash .env theme={"dark"}
  # 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
  ```

  ```bash .env theme={"dark"}
  # Or keep both during transition
  OPENAI_API_KEY=sk-xxx
  MAVERA_API_KEY=mvra_live_xxx
  ```
</CodeGroup>

### 4. Change Client Configuration

<CodeGroup>
  ```python Python theme={"dark"}
  # 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",
  )
  ```

  ```javascript JavaScript theme={"dark"}
  // 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",
  });
  ```

  ```go Go theme={"dark"}
  // 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)
  ```
</CodeGroup>

### 5. Add persona\_id to Requests

<CodeGroup>
  ```python Python theme={"dark"}
  # 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"},
  )
  ```

  ```javascript JavaScript theme={"dark"}
  // 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",
  });
  ```
</CodeGroup>

<Tip>
  **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.
</Tip>

***

## 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`.

<CodeGroup>
  ```python Python theme={"dark"}
  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": [...]},
  )
  ```

  ```javascript JavaScript theme={"dark"}
  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" }),
  });
  ```
</CodeGroup>

***

## Migration Checklist

<AccordionGroup>
  <Accordion title="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`
  </Accordion>

  <Accordion title="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)
  </Accordion>

  <Accordion title="Environment & config">
    * [ ] Add `MAVERA_API_KEY` to env (or repoint `OPENAI_API_KEY`)
    * [ ] Update any config files or secrets managers
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="Production">
    * [ ] Deploy behind feature flag or canary if possible
    * [ ] Monitor [Credits](/guides/credits) and [Rate Limits](/guides/rate-limits)
    * [ ] Set up [Error Handling](/cookbooks/error-handling-patterns) for 401, 402, 429
  </Accordion>
</AccordionGroup>

***

## Common Gotchas

<AccordionGroup>
  <Accordion title="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"}`.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Credits vs tokens">
    Mavera uses **credits**, not token-based pricing. Each response includes `usage.credits_used`. See [Credits](/guides/credits).
  </Accordion>

  <Accordion title="Different rate limits">
    Mavera rate limits differ by tier. See [Rate Limits](/guides/rate-limits). If you were batching heavily on OpenAI, you may need to throttle.
  </Accordion>
</AccordionGroup>

***

## See Also

<CardGroup cols={2}>
  <Card title="Quickstart: Chat" icon="comments" href="/quickstart-chat">
    First Mavera request with persona
  </Card>

  <Card title="SDKs Overview" icon="plug" href="/sdks/overview">
    Python, JavaScript, Go, and REST usage
  </Card>

  <Card title="Responses API" icon="code" href="/features/responses">
    Full feature set: streaming, tools, analysis mode
  </Card>

  <Card title="Persona Selection" icon="user" href="/cookbooks/persona-selection">
    How to choose the right persona
  </Card>
</CardGroup>