Migrate from Chat Completions to Responses API

Mavera has migrated from the OpenAI Chat Completions format to the OpenAI Responses API format. This guide walks you through every change — endpoints, SDK methods, request/response shapes, streaming, tool calling, and structured outputs.

The Responses API is not a breaking version bump — it’s a new endpoint format. Your existing Chat Completions code will continue to work during the transition period, but all new features and documentation target the Responses API.

What Changed

Concept	Chat Completions (old)	Responses API (new)
Endpoint	`POST /api/v1/chat/completions`	`POST /api/v1/responses`
SDK method	`client.chat.completions.create()`	`client.responses.create()`
Input	`messages: [{role, content}]`	`input: "string"` or `input: [{role, content}]`
System message	`{role: "system", content: "..."}` in messages	`instructions` parameter
Output text	`response.choices[0].message.content`	`response.output[0].content[0].text`
Streaming (Python)	`stream=True` + `for chunk in stream:`	`client.responses.stream()` context manager
Streaming (JS)	`stream: true` + `for await`	`client.responses.stream()` + `.on()` events
Tool format	`{type, function: {name, description, parameters}}`	`{type, name, description, parameters}` (flat)
Tool call output	`response.choices[0].message.tool_calls`	Items in `response.output` with `type == "function_call"`
Tool result	`{role: "tool", tool_call_id, content}`	`{type: "function_call_output", call_id, output}`
Structured output	`response_format: {type, json_schema}`	`text: {format: {type, json_schema}}` via `extra_body`
Parsed output	`response.choices[0].message.parsed`	`response.parsed`
Response ID	`chatcmpl_...`	`resp_...`
Response object	`"chat.completion"`	`"response"`
Token fields	`prompt_tokens` / `completion_tokens`	`input_tokens` / `output_tokens`
Finish signal	`choices[0].finish_reason: "stop"`	`status: "completed"`
SSE events	Generic `data:` chunks	Named events (`response.created`, `response.output_text.delta`, `response.completed`)
Credits	`usage.credits_used`	`usage.credits_used` (no change)

Step-by-Step Migration

1. Update the SDK Method

The SDK method changes from chat.completions.create() to responses.create(). The input format also changes from messages to input. No SDK version change is required — the OpenAI SDK already supports both.

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)

response = client.responses.create(
    model="mavera-1",
    input="How do Gen Z consumers view sustainability?",
    instructions="You are a helpful assistant.",
    extra_body={"persona_id": "YOUR_PERSONA_ID"},
)
print(response.output[0].content[0].text)

const response = await 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?" },
  ],
  persona_id: "YOUR_PERSONA_ID",
});
console.log(response.choices[0].message.content);

const response = await client.responses.create({
  model: "mavera-1",
  input: "How do Gen Z consumers view sustainability?",
  instructions: "You are a helpful assistant.",
  // @ts-ignore - Mavera custom field
  persona_id: "YOUR_PERSONA_ID",
});
console.log(response.output[0].content[0].text);

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": "..."}]}'

curl -X POST https://app.mavera.io/api/v1/responses \
  -H "Authorization: Bearer mvra_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"model": "mavera-1", "persona_id": "YOUR_PERSONA_ID", "input": "..."}'

2. Move System Messages to `instructions`

System messages are no longer part of the messages array. Use the top-level instructions parameter instead. Instructions are appended to the persona’s built-in system prompt.

response = client.chat.completions.create(
    model="mavera-1",
    messages=[
        {"role": "system", "content": "You are a market research analyst."},
        {"role": "user", "content": "Analyze brand loyalty trends."}
    ],
    extra_body={"persona_id": "YOUR_PERSONA_ID"},
)

response = client.responses.create(
    model="mavera-1",
    input="Analyze brand loyalty trends.",
    instructions="You are a market research analyst.",
    extra_body={"persona_id": "YOUR_PERSONA_ID"},
)

3. Update Streaming

The streaming interface changes from a flag-based approach to a dedicated stream method with named events.

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:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

with client.responses.stream(
    model="mavera-1",
    input="Write a product description",
    extra_body={"persona_id": "YOUR_PERSONA_ID"},
) as stream:
    for event in stream:
        if event.type == "response.output_text.delta":
            print(event.delta, end="", flush=True)

const stream = await client.chat.completions.create({
  model: "mavera-1",
  messages: [{ role: "user", content: "Write a product description" }],
  persona_id: "YOUR_PERSONA_ID",
  stream: true,
});

for await (const chunk of stream) {
  const delta = chunk.choices[0]?.delta?.content || "";
  process.stdout.write(delta);
}

const stream = client.responses.stream({
  model: "mavera-1",
  input: "Write a product description",
  // @ts-ignore - Mavera custom field
  persona_id: "YOUR_PERSONA_ID",
});

stream.on("response.output_text.delta", (event) => {
  process.stdout.write(event.delta);
});

const finalResponse = await stream.finalResponse();

4. Update Structured Outputs

The response_format parameter is replaced by text format configuration passed via extra_body. The parsed result moves from response.choices[0].message.parsed to response.parsed.

response = client.chat.completions.create(
    model="mavera-1",
    messages=[{"role": "user", "content": "Review this product: Great quality!"}],
    extra_body={
        "persona_id": "YOUR_PERSONA_ID",
        "response_format": {
            "type": "json_schema",
            "json_schema": {
                "name": "product_review",
                "strict": True,
                "schema": {
                    "type": "object",
                    "properties": {
                        "sentiment": {"type": "string"},
                        "score": {"type": "number"},
                        "summary": {"type": "string"}
                    },
                    "required": ["sentiment", "score", "summary"]
                }
            }
        }
    },
)
data = response.choices[0].message.parsed

response = client.responses.create(
    model="mavera-1",
    input="Review this product: Great quality!",
    extra_body={
        "persona_id": "YOUR_PERSONA_ID",
        "text": {
            "format": {
                "type": "json_schema",
                "json_schema": {
                    "name": "product_review",
                    "strict": True,
                    "schema": {
                        "type": "object",
                        "properties": {
                            "sentiment": {"type": "string"},
                            "score": {"type": "number"},
                            "summary": {"type": "string"}
                        },
                        "required": ["sentiment", "score", "summary"]
                    }
                }
            }
        }
    },
)
data = response.parsed

5. Update Tool Calling

Tool definitions change from a nested format to a flat format. Tool call results change from {role: "tool"} messages to {type: "function_call_output"} items.

Tool Definitions

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"}
                },
                "required": ["location"]
            }
        }
    }
]

tools = [
    {
        "type": "function",
        "name": "get_weather",
        "description": "Get the current weather",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {"type": "string"}
            },
            "required": ["location"]
        }
    }
]

Reading Tool Calls

if response.choices[0].finish_reason == "tool_calls":
    for tc in response.choices[0].message.tool_calls:
        print(tc.function.name, tc.function.arguments)

for item in response.output:
    if item.type == "function_call":
        print(item.name, item.arguments)

Sending Tool Results

follow_up = client.chat.completions.create(
    model="mavera-1",
    messages=[
        {"role": "user", "content": "What's the weather?"},
        {"role": "assistant", "content": None, "tool_calls": [...]},
        {
            "role": "tool",
            "tool_call_id": tool_call.id,
            "content": json.dumps(result)
        }
    ],
    extra_body={"persona_id": "YOUR_PERSONA_ID"},
)

follow_up = client.responses.create(
    model="mavera-1",
    input=[
        *response.output,
        {
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": json.dumps(result)
        }
    ],
    tools=tools,
    extra_body={"persona_id": "YOUR_PERSONA_ID"},
)

6. Update Response Parsing

The response shape changes significantly. Update all code that reads from the response object.

Chat Completions (old)	Responses API (new)
`response.choices[0].message.content`	`response.output[0].content[0].text`
`response.choices[0].message.parsed`	`response.parsed`
`response.choices[0].finish_reason`	`response.status`
`response.usage.prompt_tokens`	`response.usage.input_tokens`
`response.usage.completion_tokens`	`response.usage.output_tokens`
`response.usage.credits_used`	`response.usage.credits_used` (unchanged)
`response.id` (prefix `chatcmpl_`)	`response.id` (prefix `resp_`)
`response.object` (`"chat.completion"`)	`response.object` (`"response"`)

7. Update Error Handling

Error responses use the same format, but the retry logic should reference the new SDK method.

def chat_with_retry(messages, persona_id, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(
                model="mavera-1",
                messages=messages,
                extra_body={"persona_id": persona_id},
            )
        except RateLimitError:
            time.sleep(2 ** attempt)

def respond_with_retry(input_text, persona_id, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.responses.create(
                model="mavera-1",
                input=input_text,
                extra_body={"persona_id": persona_id},
            )
        except RateLimitError:
            time.sleep(2 ** attempt)

Migration Checklist

Migration checklist

Use this checklist to verify your migration is complete:

Common Gotchas

System messages are ignored in the input array

The Responses API does not support {role: "system"} in the input array. Use the instructions parameter instead. If you include a system message in input, it will be ignored or cause an error.

Tool definitions must be flat

The old {type: "function", function: {name, ...}} nested format will not work. Use the flat format: {type: "function", name: "...", description: "...", parameters: {...}}.

Tool results use call_id, not tool_call_id

The field name changed from tool_call_id to call_id, and the message type changed from {role: "tool"} to {type: "function_call_output"}.

Streaming uses a context manager in Python

You can no longer use stream=True as a parameter. Instead, use client.responses.stream() which returns a context manager. Iterate over events and check event.type == 'response.output_text.delta'.

Structured output config key changed

response_format is replaced by text in extra_body. The schema structure inside is the same, but the wrapping key is different: text: {format: {type: "json_schema", json_schema: {...}}}.

Response shape is different

There are no more choices — the output is in response.output[]. Each output item has a type field ("message" for text, "function_call" for tool calls). Text content is at response.output[0].content[0].text.

persona_id passing is unchanged

In Python, persona_id is still passed via extra_body. In JavaScript, it’s still a top-level field with // @ts-ignore. This did not change.

Responses API

Full Responses API reference and usage guide

Migrate OpenAI to Mavera

Migrate from OpenAI to Mavera (base URL + persona)

Streaming Guide

Deep dive into streaming patterns

Function Calling Guide

Tool calling patterns and best practices

Overview

Persona Research

Content Production

Video Intelligence

Strategic Research

Fundamentals

Migrate from Chat Completions to Responses API

What Changed

Step-by-Step Migration

1. Update the SDK Method

2. Move System Messages to `instructions`

3. Update Streaming

4. Update Structured Outputs

5. Update Tool Calling

Tool Definitions

Reading Tool Calls

Sending Tool Results

6. Update Response Parsing

7. Update Error Handling

Migration Checklist

Common Gotchas

See Also

Responses API

Migrate OpenAI to Mavera

Streaming Guide

Function Calling Guide

​What Changed

​Step-by-Step Migration

​1. Update the SDK Method

​2. Move System Messages to instructions

​3. Update Streaming

​4. Update Structured Outputs

​5. Update Tool Calling

​Tool Definitions

​Reading Tool Calls

​Sending Tool Results

​6. Update Response Parsing

​7. Update Error Handling

​Migration Checklist

​Common Gotchas

​See Also

Responses API

Migrate OpenAI to Mavera

Streaming Guide

Function Calling Guide

What Changed

Step-by-Step Migration

1. Update the SDK Method

2. Move System Messages to `instructions`

3. Update Streaming

4. Update Structured Outputs

5. Update Tool Calling

Tool Definitions

Reading Tool Calls

Sending Tool Results

6. Update Response Parsing

7. Update Error Handling

Migration Checklist

Common Gotchas

See Also