Basic Usage

This guide covers the basics of using the Anannas Responses API, including simple text requests, conversation management, and handling responses.

Stateless APIThe Anannas Responses API is stateless. Each request is independent and no conversation state is stored server-side. You must include the full conversation history in every request to maintain context.

Simple Text Request

The simplest way to use the Responses API is with a plain text string:

import requests

response = requests.post(
    "https://api.anannas.ai/api/v1/responses",
    headers={
        "Authorization": "Bearer <ANANNAS_API_KEY>",
        "Content-Type": "application/json",
    },
    json={
        "model": "openai/gpt-5-mini",
        "input": "What is the capital of France?",
        "max_output_tokens": 1000,
    },
)

result = response.json()
print(result["output"][0]["content"][0]["text"])

const response = await fetch('https://api.anannas.ai/api/v1/responses', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <ANANNAS_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'openai/gpt-5-mini',
    input: 'What is the capital of France?',
    max_output_tokens: 1000,
  }),
});

const result = await response.json();
console.log(result.output[0].content[0].text);

curl https://api.anannas.ai/api/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ANANNAS_API_KEY>" \
  -d '{
    "model": "openai/gpt-5-mini",
    "input": "What is the capital of France?",
    "max_output_tokens": 1000
  }'

Structured Message Input

For more control, use structured message format with conversation history:

import requests

response = requests.post(
    "https://api.anannas.ai/api/v1/responses",
    headers={
        "Authorization": "Bearer <ANANNAS_API_KEY>",
        "Content-Type": "application/json",
    },
    json={
        "model": "openai/gpt-5-mini",
        "input": [
            {
                "type": "message",
                "role": "user",
                "content": [
                    {
                        "type": "input_text",
                        "text": "What is the capital of France?"
                    }
                ]
            }
        ],
        "max_output_tokens": 1000,
    },
)

result = response.json()
print(result["output"][0]["content"][0]["text"])

const response = await fetch('https://api.anannas.ai/api/v1/responses', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <ANANNAS_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'openai/gpt-5-mini',
    input: [
      {
        type: 'message',
        role: 'user',
        content: [
          {
            type: 'input_text',
            text: 'What is the capital of France?',
          },
        ],
      },
    ],
    max_output_tokens: 1000,
  }),
});

const result = await response.json();
console.log(result.output[0].content[0].text);

Multi-Turn Conversations

Important: Stateless DesignThe Anannas Responses API is stateless - it does not maintain conversation state between requests. Unlike OpenAI’s stateful Responses API, you must include the complete conversation history in every request. Each request is treated as independent.

Since the API is stateless, you must include the full conversation history in each request:

import requests

# First request
first_response = requests.post(
    "https://api.anannas.ai/api/v1/responses",
    headers={
        "Authorization": "Bearer <ANANNAS_API_KEY>",
        "Content-Type": "application/json",
    },
    json={
        "model": "openai/gpt-5-mini",
        "input": [
            {
                "type": "message",
                "role": "user",
                "content": [
                    {
                        "type": "input_text",
                        "text": "What is the capital of France?"
                    }
                ]
            }
        ],
        "max_output_tokens": 1000,
    },
)

first_result = first_response.json()
assistant_message = first_result["output"][0]

# Second request - include previous conversation
second_response = requests.post(
    "https://api.anannas.ai/api/v1/responses",
    headers={
        "Authorization": "Bearer <ANANNAS_API_KEY>",
        "Content-Type": "application/json",
    },
    json={
        "model": "openai/gpt-5-mini",
        "input": [
            {
                "type": "message",
                "role": "user",
                "content": [
                    {
                        "type": "input_text",
                        "text": "What is the capital of France?"
                    }
                ]
            },
            {
                "type": "message",
                "role": "assistant",
                "status": "completed",
                "content": assistant_message["content"]
            },
            {
                "type": "message",
                "role": "user",
                "content": [
                    {
                        "type": "input_text",
                        "text": "What is the population of that city?"
                    }
                ]
            }
        ],
        "max_output_tokens": 1000,
    },
)

second_result = second_response.json()
print(second_result["output"][0]["content"][0]["text"])

// First request
const firstResponse = await fetch('https://api.anannas.ai/api/v1/responses', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <ANANNAS_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'openai/gpt-5-mini',
    input: [
      {
        type: 'message',
        role: 'user',
        content: [
          {
            type: 'input_text',
            text: 'What is the capital of France?',
          },
        ],
      },
    ],
    max_output_tokens: 1000,
  }),
});

const firstResult = await firstResponse.json();
const assistantMessage = firstResult.output[0];

// Second request - include previous conversation
const secondResponse = await fetch('https://api.anannas.ai/api/v1/responses', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <ANANNAS_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'openai/gpt-5-mini',
    input: [
      {
        type: 'message',
        role: 'user',
        content: [
          {
            type: 'input_text',
            text: 'What is the capital of France?',
          },
        ],
      },
      {
        type: 'message',
        role: 'assistant',
        status: 'completed',
        content: assistantMessage.content,
      },
      {
        type: 'message',
        role: 'user',
        content: [
          {
            type: 'input_text',
            text: 'What is the population of that city?',
          },
        ],
      },
    ],
    max_output_tokens: 1000,
  }),
});

const secondResult = await secondResponse.json();
console.log(secondResult.output[0].content[0].text);

Using Instructions

You can provide system-level instructions to guide the model’s behavior:

import requests

response = requests.post(
    "https://api.anannas.ai/api/v1/responses",
    headers={
        "Authorization": "Bearer <ANANNAS_API_KEY>",
        "Content-Type": "application/json",
    },
    json={
        "model": "openai/gpt-5-mini",
        "input": "Explain quantum computing in simple terms.",
        "instructions": "You are a helpful science teacher. Explain concepts clearly and use analogies when helpful.",
        "max_output_tokens": 2000,
    },
)

result = response.json()
print(result["output"][0]["content"][0]["text"])

const response = await fetch('https://api.anannas.ai/api/v1/responses', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <ANANNAS_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'openai/gpt-5-mini',
    input: 'Explain quantum computing in simple terms.',
    instructions: 'You are a helpful science teacher. Explain concepts clearly and use analogies when helpful.',
    max_output_tokens: 2000,
  }),
});

const result = await response.json();
console.log(result.output[0].content[0].text);

Handling Responses

The response contains an output array with one or more output items. Each item has:

type: The type of output (usually “message”)
role: The role of the message (usually “assistant”)
status: The status of the output (“completed”, “incomplete”, etc.)
content: An array of content parts

Extracting Text Content:

result = response.json()

# Get the first output item
output_item = result["output"][0]

# Extract text from content
for content_part in output_item["content"]:
    if content_part["type"] == "output_text":
        print(content_part["text"])

const result = await response.json();

// Get the first output item
const outputItem = result.output[0];

// Extract text from content
for (const contentPart of outputItem.content) {
  if (contentPart.type === 'output_text') {
    console.log(contentPart.text);
  }
}

Error Handling

Always check for errors in the response:

response = requests.post(
    "https://api.anannas.ai/api/v1/responses",
    headers={
        "Authorization": "Bearer <ANANNAS_API_KEY>",
        "Content-Type": "application/json",
    },
    json={
        "model": "openai/gpt-5-mini",
        "input": "Hello!",
    },
)

if response.status_code != 200:
    error = response.json()
    print(f"Error: {error['error']['message']}")
else:
    result = response.json()
    print(result["output"][0]["content"][0]["text"])

const response = await fetch('https://api.anannas.ai/api/v1/responses', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <ANANNAS_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'openai/gpt-5-mini',
    input: 'Hello!',
  }),
});

if (!response.ok) {
  const error = await response.json();
  console.error(`Error: ${error.error.message}`);
} else {
  const result = await response.json();
  console.log(result.output[0].content[0].text);
}

Best Practices

Always include conversation history: Since the Anannas API is stateless, include all previous messages in each request. The Anannas API does not remember previous conversations.
Manage state client-side: You are responsible for maintaining conversation history and including it in each request.
Set appropriate token limits: Use max_output_tokens to control response length
Handle errors gracefully: Check response status codes and error messages
Use structured input: Prefer structured message format for better control and multimodal support
Monitor usage: Check the usage field in responses to track token consumption

Stateless vs StatefulOpenAI’s Responses API has both stateless and stateful versions. Anannas implements only the stateless version, which means:

No server-side conversation state
No previous_response_id parameter support
You must include full conversation history in each request
Each request is completely independent

Was this page helpful?

Getting Started

Features

API

Models

Use Cases

Community

Simple Text Request

Structured Message Input

Multi-Turn Conversations

Using Instructions

Handling Responses

Error Handling

Best Practices

​Simple Text Request

​Structured Message Input

​Multi-Turn Conversations

​Using Instructions

​Handling Responses

​Error Handling

​Best Practices

Simple Text Request

Structured Message Input

Multi-Turn Conversations

Using Instructions

Handling Responses

Error Handling

Best Practices