Basic Usage

Responses API Beta

The Responses API Beta supports both simple string input and structured message arrays, making it easy to get started with basic text generation.

Simple String Input

The simplest way to use the API is with a string input:

responses-basic-usage-01.js


const response = await fetch("https://novapai.ai/api/v1/responses", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_NOVASTACK_AI_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "openai/o4-mini",
    input: "What is the meaning of life?",
    max_output_tokens: 9000,
  }),
});
 
const result = await response.json();
console.log(result);

Structured Message Input

For more complex conversations, use the message array format:

responses-basic-usage-02.js


const response = await fetch('https://novapai.ai/api/v1/responses', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_NOVASTACK_AI_API_KEY',
      'Content-Type': 'application/json',
    },
  body: JSON.stringify({
      model: 'openai/o4-mini',
      input: [
        {
          type: 'message',
          role: 'user',
          content: [
            {
              type: 'input_text',
              text: 'Tell me a joke about programming',
            },
        ],
    },
],
max_output_tokens: 9000,
}),
});
 
const result = await response.json();
```json showLineNumbers filename="responses-basic-usage-03.json"
 
## Response Format
 
The API returns a structured response with the generated content:
```json showLineNumbers filename="responses-basic-usage-04.json"
{
  "id": "resp_1234567890",
  "object": "response",
  "created_at": 1234567890,
  "model": "openai/o4-mini",
  "output": [
    {
      "type": "message",
      "id": "msg_abc123",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "The meaning of life is a philosophical question that has been pondered for centuries...",
          "annotations": []
        }
    ]
}
],
"usage": {
  "input_tokens": 12,
  "output_tokens": 45,
  "total_tokens": 57
},
"status": "completed"
}

Streaming Responses

Enable streaming for real-time response generation:

responses-basic-usage-05.js


const response = await fetch("https://novapai.ai/api/v1/responses", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_NOVASTACK_AI_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "openai/o4-mini",
    input: "Write a short story about AI",
    stream: true,
    max_output_tokens: 9000,
  }),
});
 
const reader = response.body?.getReader();
const decoder = new TextDecoder();
 
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
 
  const chunk = decoder.decode(value);
  const lines = chunk.split("\n");
 
  for (const line of lines) {
    if (line.startsWith("data: ")) {
      const data = line.slice(6);
      if (data === "[DONE]") return;
 
      try {
        const parsed = JSON.parse(data);
        console.log(parsed);
      } catch (e) {
        // Skip invalid JSON
      }
    }
  }
}

Example Streaming Output

The streaming response returns Server-Sent Events (SSE) chunks:

Common Parameters

Parameter	Type	Description
`model`	string	Required. Model to use (e.g., `openai/o4-mini`)
`input`	string or array	Required. Text or message array
`stream`	boolean	Enable streaming responses (default: false)
`max_output_tokens`	integer	Maximum tokens to generate
`temperature`	number	Sampling temperature (0-2)
`top_p`	number	Nucleus sampling parameter (0-1)

Error Handling

Handle common errors gracefully:

responses-basic-usage-06.js


try {
  const response = await fetch("https://novapai.ai/api/v1/responses", {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_NOVASTACK_AI_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "openai/o4-mini",
      input: "Hello, world!",
    }),
  });
 
  if (!response.ok) {
    const error = await response.json();
    console.error("API Error:", error.error.message);
    return;
  }
 
  const result = await response.json();
  console.log(result);
} catch (error) {
  console.error("Network Error:", error);
}

Multiple Turn Conversations

Since the Responses API Beta is stateless, you must include the full conversation history in each request to maintain context:

responses-basic-usage-07.js


// First request
const firstResponse = await fetch('https://novapai.ai/api/v1/responses', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_NOVASTACK_AI_API_KEY',
      'Content-Type': 'application/json',
    },
  body: JSON.stringify({
      model: 'openai/o4-mini',
      input: [
        {
          type: 'message',
          role: 'user',
          content: [
            {
              type: 'input_text',
              text: 'What is the capital of France?',
            },
        ],
    },
],
max_output_tokens: 9000,
}),
});
 
const firstResult = await firstResponse.json();
 
// Second request - include previous conversation
const secondResponse = await fetch('https://novapai.ai/api/v1/responses', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_NOVASTACK_AI_API_KEY',
      'Content-Type': 'application/json',
    },
  body: JSON.stringify({
      model: 'openai/o4-mini',
      input: [
        {
          type: 'message',
          role: 'user',
          content: [
            {
              type: 'input_text',
              text: 'What is the capital of France?',
            },
        ],
    },
  {
    type: 'message',
    role: 'assistant',
    id: 'msg_abc123',
    status: 'completed',
    content: [
      {
        type: 'output_text',
        text: 'The capital of France is Paris.',
        annotations: []
      }
  ]
},
{
  type: 'message',
  role: 'user',
  content: [
    {
      type: 'input_text',
      text: 'What is the population of that city?',
    },
],
},
],
max_output_tokens: 9000,
}),
});
 
const secondResult = await secondResponse.json();
```json showLineNumbers filename="responses-basic-usage-08.json"
 
##### Required Fields
 
The `id` and `status` fields are required for any `assistant` role messages included in the conversation history.
 
##### Conversation History
 
Always include the complete conversation history in each request. The API does not store previous messages, so context must be maintained client-side.
 
## Next Steps
 
*   Learn about [Reasoning](https://novapai.ai/docs/api/reference/responses/reasoning) capabilities
*   Explore [Tool Calling](https://novapai.ai/docs/api/reference/responses/tool-calling) functionality
*   Try [Web Search](https://novapai.ai/docs/api/reference/responses/web-search) integration