NagaAI

https://docs.naga.ac/
Admin
NagaAI is a unified AI platform providing model access, API routing, and tool-compatible...
Tokens:118,154
Snippets:873
Trust Score:6
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install Dependencies and Start Gemini CLI

Source: https://docs.naga.ac/integrations/agents/gemini-cli

Install the necessary Node.js dependencies and start the Gemini CLI application. Requires Node.js 18+.

```bash
npm install
npm start
```

--------------------------------

### Install OpenCode using npm

Source: https://docs.naga.ac/integrations/agents/opencode

Install OpenCode globally using npm. This requires Node.js and npm to be installed.

```bash
npm install -g opencode-ai
```

--------------------------------

### Install OpenCode using curl

Source: https://docs.naga.ac/integrations/agents/opencode

Install OpenCode using the official install script. Ensure you have curl installed.

```bash
curl -fsSL https://opencode.ai/install | bash
```

--------------------------------

### Create Audio Transcription (Node.js)

Source: https://docs.naga.ac/api/audio/speech-to-text

This Node.js example demonstrates how to transcribe audio to text. You need to install the `openai` package and provide your API key. The `file` parameter should be a readable stream created from your audio file.

```javascript
import fs from 'fs';
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.naga.ac/v1',
  apiKey: 'YOUR_API_KEY',
});

const transcription = await client.audio.transcriptions.create({
  model: 'whisper-1',
  file: fs.createReadStream('meeting.mp3'),
  language: 'en',
  prompt: 'Preserve product names exactly as spoken.',
});

console.log(transcription.text);
```

--------------------------------

### Install OpenAI SDK

Source: https://docs.naga.ac/get-started/quickstart

Install the official OpenAI SDK for Python or Node.js to interact with NagaAI.

```bash
pip install openai
```

```bash
npm install openai
```

--------------------------------

### Create a Message with Node.js

Source: https://docs.naga.ac/api/messages

This Node.js example demonstrates how to send a user message and retrieve a text response using the Anthropic SDK. Make sure to install the SDK and set your API key.

```javascript
import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  baseURL: 'https://api.naga.ac',
  apiKey: 'YOUR_API_KEY',
});

const message = await client.messages.create({
  model: 'claude-sonnet-4.5',
  max_tokens: 256,
  messages: [
    { role: 'user', content: 'Explain circuit breakers in simple terms.' },
  ],
});

console.log(message.content[0].text);
```

--------------------------------

### Example Cost Calculation

Source: https://docs.naga.ac/build/billing

Illustrates how to calculate the cost of a model request based on input and output tokens and their respective prices. This example uses hypothetical token prices.

```text
Hello! Can you help me?
```

```text
Hello! I'd be happy to help you. What do you need assistance with today?
```

--------------------------------

### File Example

Source: https://docs.naga.ac/api/chat-completions/multimodal-content

This example demonstrates how to send a PDF file as part of a chat completion request. The file is referenced via a URL.

```APIDOC
## File Example

This example demonstrates how to send a PDF file as part of a chat completion request. The file is referenced via a URL.

### Python
```python
from openai import OpenAI

client = OpenAI(
    base_url="https://api.naga.ac/v1",
    api_key="YOUR_API_KEY",
)

completion = client.chat.completions.create(
    model="gpt-5",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Summarize this PDF."},
                {
                    "type": "file",
                    "file": {
                        "filename": "report.pdf",
                        "file_data": "https://example.com/report.pdf",
                    },
                },
            ],
        }
    ],
)

print(completion.choices[0].message.content)
```

### Node.js
```javascript
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.naga.ac/v1',
  apiKey: 'YOUR_API_KEY',
});

const completion = await client.chat.completions.create({
  model: 'gpt-5',
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'Summarize this PDF.' },
        {
          type: 'file',
          file: {
            filename: 'report.pdf',
            file_data: 'https://example.com/report.pdf',
          },
        },
      ],
    },
  ],
});

console.log(completion.choices[0].message.content);
```

### cURL
```bash
curl https://api.naga.ac/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d 
    {
      "model": "gpt-5",
      "messages": [
        {
          "role": "user",
          "content": [
            { "type": "text", "text": "Summarize this PDF." },
            {
              "type": "file",
              "file": {
                "filename": "report.pdf",
                "file_data": "https://example.com/report.pdf"
              }
            }
          ]
        }
      ]
    }
```
```

--------------------------------

### Audio Example

Source: https://docs.naga.ac/api/chat-completions/multimodal-content

This example shows how to include audio data in a chat completion request. The audio data should be base64 encoded.

```APIDOC
## Audio Example

This example shows how to include audio data in a chat completion request. The audio data should be base64 encoded.

### Python
```python
from openai import OpenAI

client = OpenAI(
    base_url="https://api.naga.ac/v1",
    api_key="YOUR_API_KEY",
)

completion = client.chat.completions.create(
    model="gemini-2.5-flash",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Tell me what is said in this audio."},
                {
                    "type": "input_audio",
                    "input_audio": {
                        "data": "BASE64_AUDIO",
                        "format": "wav",
                    },
                },
            ],
        }
    ],
)

print(completion.choices[0].message.content)
```

### Node.js
```javascript
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.naga.ac/v1',
  apiKey: 'YOUR_API_KEY',
});

const completion = await client.chat.completions.create({
  model: 'gemini-2.5-flash',
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'Tell me what is said in this audio.' },
        {
          type: 'input_audio',
          input_audio: {
            data: 'BASE64_AUDIO',
            format: 'wav',
          },
        },
      ],
    },
  ],
});

console.log(completion.choices[0].message.content);
```

### cURL
```bash
curl https://api.naga.ac/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d 
    {
      "model": "gemini-2.5-flash",
      "messages": [
        {
          "role": "user",
          "content": [
            { "type": "text", "text": "Tell me what is said in this audio." },
            {
              "type": "input_audio",
              "input_audio": {
                "data": "BASE64_AUDIO",
                "format": "wav"
              }
            }
          ]
        }
      ]
    }
```
```

--------------------------------

### Web Search Request Examples

Source: https://docs.naga.ac/api/responses/web-search

Examples of how to initiate a web search request using the Responses API in Python, Node.js, and cURL.

```APIDOC
## Web Search Request

### Description
Initiate a request to the Responses API with the `web_search` tool enabled to allow the model to fetch current web content.

### Method
POST

### Endpoint
/v1/responses

### Request Body
- **model** (string) - Required - The model to use for the response.
- **input** (string) - Required - The user's prompt or query.
- **tools** (array) - Required - A list of tools to use. For web search, include `{"type": "web_search"}`.

### Request Example (Python)
```python
from openai import OpenAI

client = OpenAI(
    base_url="https://api.naga.ac/v1",
    api_key="YOUR_API_KEY",
)

response = client.responses.create(
    model="gpt-4.1",
    input="Find recent reporting about AI regulation in the UK and cite your sources.",
    tools=[{"type": "web_search"}],
)

print(response.output_text)
```

### Request Example (Node.js)
```javascript
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.naga.ac/v1',
  apiKey: 'YOUR_API_KEY',
});

const response = await client.responses.create({
  model: 'gpt-4.1',
  input: 'Find recent reporting about AI regulation in the UK and cite your sources.',
  tools: [{ type: 'web_search' }],
});

console.log(response.output_text);
```

### Request Example (cURL)
```bash
curl https://api.naga.ac/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "input": "Find recent reporting about AI regulation in the UK and cite your sources.",
    "tools": [
      {
        "type": "web_search"
      }
    ]
  }'
```
```

--------------------------------

### Start Codex CLI

Source: https://docs.naga.ac/integrations/agents/codex-cli

Run this command in your project directory to start Codex CLI. It will use the NagaAI provider configured in `config.toml`.

```bash
codex
```

--------------------------------

### Stream Model Output with Node.js

Source: https://docs.naga.ac/build/streaming

This Node.js example demonstrates how to stream output from the Responses API. Make sure to install the 'openai' package and provide your API key.

```javascript
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.naga.ac/v1',
  apiKey: 'YOUR_API_KEY',
});

const stream = await client.responses.create({
  model: 'gpt-4.1-mini',
  input: 'Stream a short explanation of backpressure.',
  stream: true,
});

for await (const event of stream) {
  if (event.type === 'response.output_text.delta') {
    process.stdout.write(event.delta);
  }
}
```

--------------------------------

### Install Claude Code (npm)

Source: https://docs.naga.ac/integrations/agents/claude-code

Install Claude Code globally using npm.

```bash
npm install -g @anthropic-ai/claude-code
```

--------------------------------

### Start OpenCode in a project directory

Source: https://docs.naga.ac/integrations/agents/opencode

Initiate an OpenCode session within your project's root directory. This command should be run from your terminal.

```bash
opencode
```

--------------------------------

### Account Request Example

Source: https://docs.naga.ac/get-started/authentication

Make a request to an account endpoint using your provisioning key. Supports Python, Node.js, and cURL.

```python
import requests

response = requests.get(
    "https://api.naga.ac/v1/account/balance",
    headers={"Authorization": "Bearer YOUR_PROVISIONING_KEY"},
)
response.raise_for_status()

print(response.json()["balance"])
```

```javascript
const response = await fetch('https://api.naga.ac/v1/account/balance', {
  headers: {
    Authorization: 'Bearer YOUR_PROVISIONING_KEY',
  },
});

if (!response.ok) {
  throw new Error(`Request failed: ${response.status}`);
}

const data = await response.json();
console.log(data.balance);
```

```bash
curl https://api.naga.ac/v1/account/balance \
  -H "Authorization: Bearer YOUR_PROVISIONING_KEY"
```

--------------------------------

### Chat Completions API Quick Example

Source: https://docs.naga.ac/api/chat-completions

Demonstrates how to use the Chat Completions API with Python, Node.js, and cURL.

```APIDOC
## Chat Completions API Quick Example

This section provides examples of how to interact with the Chat Completions API using different programming languages and tools.

### Python Example
```python
from openai import OpenAI

client = OpenAI(
    base_url="https://api.naga.ac/v1",
    api_key="YOUR_API_KEY",
)

completion = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "user", "content": "Explain retries in one paragraph."}
    ],
)

print(completion.choices[0].message.content)
```

### Node.js Example
```javascript
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.naga.ac/v1',
  apiKey: 'YOUR_API_KEY',
});

const completion = await client.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [
    { role: 'user', content: 'Explain retries in one paragraph.' },
  ],
});

console.log(completion.choices[0].message.content);
```

### cURL Example
```bash
curl https://api.naga.ac/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ 
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Explain retries in one paragraph."}
    ]
  }'
```
```

--------------------------------

### Enable Streaming

Source: https://docs.naga.ac/api/responses/streaming

Demonstrates how to enable streaming by setting `stream: true` in the API request. Includes examples in Python, Node.js, and cURL.

```APIDOC
## Enable Streaming

Set `stream: true` to receive semantic Server-Sent Events instead of waiting for one final JSON response.

Use this when you want to render text progressively, react to tool calls early, or inspect structured lifecycle events.

<CodeGroup>
  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      base_url="https://api.naga.ac/v1",
      api_key="YOUR_API_KEY",
  )

  stream = client.responses.create(
      model="gpt-4.1-mini",
      input="Stream a short explanation of backpressure.",
      stream=True,
  )

  for event in stream:
      if event.type == "response.output_text.delta":
          print(event.delta, end="")
  ```

  ```javascript Node.js theme={null}
  import OpenAI from 'openai';

  const client = new OpenAI({
    baseURL: 'https://api.naga.ac/v1',
    apiKey: 'YOUR_API_KEY',
  });

  const stream = await client.responses.create({
    model: 'gpt-4.1-mini',
    input: 'Stream a short explanation of backpressure.',
    stream: true,
  });

  for await (const event of stream) {
    if (event.type === 'response.output_text.delta') {
      process.stdout.write(event.delta);
    }
  }
  ```

  ```bash cURL theme={null}
  curl -N https://api.naga.ac/v1/responses \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ \
      "model": "gpt-4.1-mini", \
      "input": "Stream a short explanation of backpressure.", \
      "stream": true \
    }'
  ```
</CodeGroup>
```

--------------------------------

### Manual SSE Parsing Example

Source: https://docs.naga.ac/api/responses/streaming

Provides a JavaScript example for manually parsing Server-Sent Events (SSE) from the streaming API response.

```APIDOC
## Manual SSE Parsing Example

```javascript theme={null}
const response = await fetch('https://api.naga.ac/v1/responses', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-4.1-mini',
    input: 'Say hello in two words.',
    stream: true,
  }),
});

const decoder = new TextDecoder();
let buffer = '';
let text = '';

for await (const chunk of response.body) {
  buffer += decoder.decode(chunk, { stream: true });

  let splitIndex;
  while ((splitIndex = buffer.indexOf('\n\n')) >= 0) {
    const frame = buffer.slice(0, splitIndex);
    buffer = buffer.slice(splitIndex + 2);

    const dataLine = frame.split('\n').find((line) => line.startsWith('data: '));
    if (!dataLine) continue;

    const data = dataLine.slice(6);
    if (data === '[DONE]') continue;

    const payload = JSON.parse(data);
    if (payload.type === 'response.output_text.delta') {
      text += payload.delta;
    }
  }
}

console.log(text);
```
```

--------------------------------

### Multi-Turn Conversation Example

Source: https://docs.naga.ac/api/responses/conversation-state

Pass previous context back to the model for a follow-up question by including structured message items in the `input` array. This example demonstrates sending user and assistant messages to maintain conversational flow.

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://api.naga.ac/v1",
    api_key="YOUR_API_KEY",
)

response = client.responses.create(
    model="gpt-4.1-mini",
    input=[
        {"type": "message", "role": "user", "content": "My name is Alice."},
        {"type": "message", "role": "assistant", "content": "Hello Alice! How can I help you today?"},
        {"type": "message", "role": "user", "content": "What is my name?"}
    ]
)

print(response.output_text)
# Output: Your name is Alice.
```

```javascript
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.naga.ac/v1',
  apiKey: 'YOUR_API_KEY',
});

const response = await client.responses.create({
  model: 'gpt-4.1-mini',
  input: [
    { type: 'message', role: 'user', content: 'My name is Alice.' },
    { type: 'message', role: 'assistant', content: 'Hello Alice! How can I help you today?' },
    { type: 'message', role: 'user', content: 'What is my name?' }
  ]
});

console.log(response.output_text);
// Output: Your name is Alice.
```

```bash
curl https://api.naga.ac/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "model": "gpt-4.1-mini",
      "input": [
          {"type": "message", "role": "user", "content": "My name is Alice.",},
          {"type": "message", "role": "assistant", "content": "Hello Alice! How can I help you today?"},
          {"type": "message", "role": "user", "content": "What is my name?"}
      ]
    }'
```

--------------------------------

### Standard Request Example

Source: https://docs.naga.ac/get-started/authentication

Make a standard API request using your API key. Supports Python, Node.js, and cURL.

```python
import requests

response = requests.post(
    "https://api.naga.ac/v1/responses",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "gpt-4.1-mini",
        "input": "Say hello.",
    },
)
response.raise_for_status()

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

```javascript
const response = await fetch('https://api.naga.ac/v1/responses', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-4.1-mini',
    input: 'Say hello.',
  }),
});

if (!response.ok) {
  throw new Error(`Request failed: ${response.status}`);
}

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

```bash
curl https://api.naga.ac/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4.1-mini","input":"Say hello."}'
```

--------------------------------

### Event Lifecycle Example

Source: https://docs.naga.ac/api/messages/streaming

A typical text stream begins with `message_start` and concludes with `message_stop`. Listen for these and other events like `content_block_delta` to process streamed data.

```text
event: message_start
data: {...}

event: content_block_start
data: {...}

event: content_block_delta
data: {"delta":{"type":"text_delta","text":"Hello"}}

event: message_delta
data: {"delta":{"stop_reason":"end_turn","stop_sequence":null}}

event: message_stop
data: {...}
```

--------------------------------

### Start Claude Code

Source: https://docs.naga.ac/integrations/agents/claude-code

Launch Claude Code from your project directory. Requests will be routed through NagaAI's Anthropic-compatible endpoint.

```bash
claude
```

--------------------------------

### Messages API with Web Search - Node.js

Source: https://docs.naga.ac/api/messages/web-search

Example of using the Messages API with the web search tool enabled in Node.js. Ensure you have the Anthropic Node.js SDK installed and your API key configured.

```javascript
import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  baseURL: 'https://api.naga.ac',
  apiKey: 'YOUR_API_KEY',
});

const message = await client.messages.create({
  model: 'claude-sonnet-4.5',
  max_tokens: 256,
  messages: [
    {
      role: 'user',
      content: 'Find the latest Reuters coverage about AI regulation in the UK and cite your sources.',
    },
  ],
  tools: [
    {
      type: 'web_search_20250305',
      name: 'web_search',
    },
  ],
});

console.log(message.content);
```

--------------------------------

### Instructions vs Input Items

Source: https://docs.naga.ac/api/responses/text-generation

This section explains how to use `instructions` for high-level guidance and `input` for the actual request payload. It also shows how to send structured input items, such as multiple messages or multimodal content, for more complex interactions.

```APIDOC
## Instructions vs Input Items

Use `instructions` for high-level developer guidance and `input` for the actual request payload. It also shows how to send structured input items, such as multiple messages or multimodal content, for more complex interactions.

### Plain Text Input Example
```json
{
  "model": "gpt-4.1-mini",
  "instructions": "Respond in two concise bullet points.",
  "input": "Explain the difference between caching and buffering."
}
```

### Structured Input Example
```json
{
  "model": "gpt-4.1-mini",
  "input": [
    {
      "type": "message",
      "role": "developer",
      "content": "Answer like an SRE writing internal notes."
    },
    {
      "type": "message",
      "role": "user",
      "content": "Explain retry storms."
    }
  ]
}
```

Use a plain string for simple one-shot prompts. Use structured `message` items when you need multiple turns, multimodal content, or fine-grained control over roles.
```

--------------------------------

### Messages API with Web Search - Python

Source: https://docs.naga.ac/api/messages/web-search

Example of using the Messages API with the web search tool enabled in Python. Ensure you have the Anthropic Python SDK installed and your API key configured.

```python
from anthropic import Anthropic

client = Anthropic(
    base_url="https://api.naga.ac",
    api_key="YOUR_API_KEY",
)

message = client.messages.create(
    model="claude-sonnet-4.5",
    max_tokens=256,
    messages=[
        {
            "role": "user",
            "content": "Find the latest Reuters coverage about AI regulation in the UK and cite your sources.",
        }
    ],
    tools=[
        {
            "type": "web_search_20250305",
            "name": "web_search",
        }
    ],
)

print(message.content)
```

--------------------------------

### Text to Speech Request Example

Source: https://docs.naga.ac/api/audio/text-to-speech

Use this snippet to convert text into streamed audio bytes. Ensure you have the necessary client library installed and your API key configured. The response is streamed audio, not JSON.

```Python
from pathlib import Path
from openai import OpenAI

client = OpenAI(
    base_url="https://api.naga.ac/v1",
    api_key="YOUR_API_KEY",
)

speech_file = Path("speech.mp3")

with client.audio.speech.with_streaming_response.create(
    model="gpt-4o-mini-tts",
    input="Welcome to NagaAI. Your job finished successfully.",
    voice="alloy",
    response_format="mp3",
) as response:
    response.stream_to_file(speech_file)
```

```Node.js
import fs from 'fs';
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.naga.ac/v1',
  apiKey: 'YOUR_API_KEY',
});

const response = await client.audio.speech.create({
  model: 'gpt-4o-mini-tts',
  input: 'Welcome to NagaAI. Your job finished successfully.',
  voice: 'alloy',
  response_format: 'mp3',
});

const buffer = Buffer.from(await response.arrayBuffer());
await fs.promises.writeFile('speech.mp3', buffer);
```

```cURL
curl https://api.naga.ac/v1/audio/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini-tts",
    "input": "Welcome to NagaAI. Your job finished successfully.",
    "voice": "alloy",
    "response_format": "mp3"
  }' \
  --output speech.mp3
```

--------------------------------

### Node.js Example for JSON Schema Enforcement

Source: https://docs.naga.ac/build/structured-outputs

This Node.js code demonstrates how to extract event details using JSON schema enforcement. Install the OpenAI Node.js library and replace 'YOUR_API_KEY' with your valid API key.

```javascript
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.naga.ac/v1',
  apiKey: 'YOUR_API_KEY',
});

const response = await client.responses.create({
  model: 'gpt-4.1',
  input: 'Extract the event details from: Alice and Bob are going to a science fair on Friday.',
  text: {
    format: {
      type: 'json_schema',
      name: 'calendar_event',
      schema: {
        type: 'object',
        properties: {
          name: { type: 'string' },
          date: { type: 'string' },
          participants: {
            type: 'array',
            items: { type: 'string' },
          },
        },
        required: ['name', 'date', 'participants'],
        additionalProperties: false,
      },
      strict: true,
    },
  },
});

console.log(response.output_text)
```

--------------------------------

### Python Example for JSON Schema Enforcement

Source: https://docs.naga.ac/build/structured-outputs

Use this Python code to extract event details into a JSON object following a defined schema. Ensure you have the OpenAI Python library installed and replace 'YOUR_API_KEY' with your actual API key.

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://api.naga.ac/v1",
    api_key="YOUR_API_KEY",
)

response = client.responses.create(
    model="gpt-4.1",
    input="Extract the event details from: Alice and Bob are going to a science fair on Friday.",
    text={
        "format": {
            "type": "json_schema",
            "name": "calendar_event",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "date": {"type": "string"},
                    "participants": {
                        "type": "array",
                        "items": {"type": "string"},
                    },
                },
                "required": ["name", "date", "participants"],
                "additionalProperties": False,
            },
            "strict": True,
        }
    },
)

print(response.output_text)
```

--------------------------------

### Request with Instructions and Input

Source: https://docs.naga.ac/api/responses/text-generation

Use the `instructions` field for high-level guidance and the `input` field for the specific request payload. This allows for more control over the response format.

```json
{
  "model": "gpt-4.1-mini",
  "instructions": "Respond in two concise bullet points.",
  "input": "Explain the difference between caching and buffering."
}
```

--------------------------------

### Install Claude Code (Windows PowerShell)

Source: https://docs.naga.ac/integrations/agents/claude-code

Install Claude Code using a PowerShell command for Windows.

```powershell
irm https://claude.ai/install.ps1 | iex
```

--------------------------------

### PDF URL Example

Source: https://docs.naga.ac/api/messages/documents-and-pdfs

Example of sending a PDF document via URL in a messages API call.

```Python
from anthropic import Anthropic

client = Anthropic(
    base_url="https://api.naga.ac",
    api_key="YOUR_API_KEY",
)

message = client.messages.create(
    model="claude-sonnet-4.5",
    max_tokens=256,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "title": "Quarterly Report",
                    "source": {
                        "type": "url",
                        "url": "https://example.com/report.pdf",
                    },
                },
                {
                    "type": "text",
                    "text": "What are the key findings in this document?",
                },
            ],
        }
    ],
)

print(message.content)
```

```Node.js
import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  baseURL: 'https://api.naga.ac',
  apiKey: 'YOUR_API_KEY',
});

const message = await client.messages.create({
  model: 'claude-sonnet-4.5',
  max_tokens: 256,
  messages: [
    {
      role: 'user',
      content: [
        {
          type: 'document',
          title: 'Quarterly Report',
          source: {
            type: 'url',
            url: 'https://example.com/report.pdf',
          },
        },
        {
          type: 'text',
          text: 'What are the key findings in this document?',
        },
      ],
    },
  ],
});

console.log(message.content);
```

```cURL
curl https://api.naga.ac/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ \
    "model": "claude-sonnet-4.5", \
    "max_tokens": 256, \
    "messages": [ \
      { \
        "role": "user", \
        "content": [ \
          { \
            "type": "document", \
            "title": "Quarterly Report", \
            "source": { \
              "type": "url", \
              "url": "https://example.com/report.pdf" \
            } \
          }, \
          { \
            "type": "text", \
            "text": "What are the key findings in this document?" \
          } \
        ] \
      } \
    ] \
    }'
```

--------------------------------

### Install Claude Code (macOS/Linux/WSL)

Source: https://docs.naga.ac/integrations/agents/claude-code

Install Claude Code using a curl command for macOS, Linux, or Windows Subsystem for Linux.

```bash
curl -fsSL https://claude.ai/install.sh | bash
```

--------------------------------

### List Startups

Source: https://docs.naga.ac/api-reference/startups/list-startups

Returns public metadata for startups and providers represented in the catalog.

```APIDOC
## GET /v1/startups

### Description
Return public metadata for startups and providers represented in the catalog.

### Method
GET

### Endpoint
/v1/startups

### Parameters

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
- **data** (array) - List of startup objects.
  - **object** (string) - Constant value: "startup".
  - **id** (string) - Unique identifier for the startup.
  - **display_name** (string) - The display name of the startup.
  - **icon_url** (string) - URL for the startup's icon.
  - **website_url** (string) - URL for the startup's website.
  - **created** (integer) - Timestamp when the startup was added.

#### Response Example
{
  "data": [
    {
      "created": 1743393600,
      "display_name": "Anthropic",
      "icon_url": "https://naga.ac/icons/anthropic.svg",
      "id": "anthropic",
      "object": "startup",
      "website_url": "https://www.anthropic.com"
    }
  ],
  "object": "list"
}
```

--------------------------------

### Quick Example: Chat Completion

Source: https://docs.naga.ac/api/chat-completions

Demonstrates how to create a chat completion using the Naga.ac API with Python, Node.js, and cURL. Ensure you have the correct base URL and API key configured.

```Python
from openai import OpenAI

client = OpenAI(
    base_url="https://api.naga.ac/v1",
    api_key="YOUR_API_KEY",
)

completion = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "user", "content": "Explain retries in one paragraph."}
    ],
)

print(completion.choices[0].message.content)
```

```javascript
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.naga.ac/v1',
  apiKey: 'YOUR_API_KEY',
});

const completion = await client.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [
    { role: 'user', content: 'Explain retries in one paragraph.' },
  ],
});

console.log(completion.choices[0].message.content);
```

```bash
curl https://api.naga.ac/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Explain retries in one paragraph."}
    ]
  }'
```

--------------------------------

### Define Tools

Source: https://docs.naga.ac/api/messages/tool-use

This example demonstrates how to define tools when creating a message. The `tools` parameter accepts an array of tool definitions, each with a name, description, and input schema.

```APIDOC
## Define Tools

Use the `tools` parameter in the `client.messages.create` method to define available tools. Each tool should have a `name`, `description`, and an `input_schema` specifying the expected input format.

### Python Example
```python
from anthropic import Anthropic

client = Anthropic(
    base_url="https://api.naga.ac",
    api_key="YOUR_API_KEY",
)

message = client.messages.create(
    model="claude-sonnet-4.5",
    max_tokens=256,
    messages=[
        {
            "role": "user",
            "content": "Check the weather in Prague and tell me if I need a coat.",
        }
    ],
    tools=[
        {
            "name": "lookup_weather",
            "description": "Look up current weather for a city.",
            "input_schema": {
                "type": "object",
                "properties": {
                    "city": {"type": "string"}
                },
                "required": ["city"],
            },
        }
    ],
)

if message.stop_reason == "tool_use":
    tool_use = next(block for block in message.content if block.type == "tool_use")
    print(tool_use.name)
    print(tool_use.input)
```

### Node.js Example
```javascript
import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  baseURL: 'https://api.naga.ac',
  apiKey: 'YOUR_API_KEY',
});

const message = await client.messages.create({
  model: 'claude-sonnet-4.5',
  max_tokens: 256,
  messages: [
    { role: 'user', content: 'Check the weather in Prague and tell me if I need a coat.' },
  ],
  tools: [
    {
      name: 'lookup_weather',
      description: 'Look up current weather for a city.',
      input_schema: {
        type: 'object',
        properties: {
          city: { type: 'string' },
        },
        required: ['city'],
      },
    },
  ],
});

if (message.stop_reason === 'tool_use') {
  const toolUse = message.content.find((block) => block.type === 'tool_use');
  console.log(toolUse?.name);
  console.log(toolUse?.input);
}
```

### cURL Example
```bash
curl https://api.naga.ac/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d 
    "{
      \"model\": \"claude-sonnet-4.5\",
      \"max_tokens\": 256,
      \"messages\": [
        {
          \"role\": \"user\",
          \"content\": \"Check the weather in Prague and tell me if I need a coat.\"
        }
      ],
      \"tools\": [
        {
          \"name\": \"lookup_weather\",
          \"description\": \"Look up current weather for a city.\",
          \"input_schema\": {
            \"type\": \"object\",
            \"properties\": {
              \"city\": { \"type\": \"string\" }
            },
            \"required\": [\"city\"]
          }
        }
      ],
      \"tool_choice\": {
        \"type\": \"auto\"
      }
    }"
```
```

--------------------------------

### Python: Initiate Web Search Request

Source: https://docs.naga.ac/api/responses/web-search

Use the `web_search` tool in your Python request to allow the model to fetch live web content. Ensure you have the `openai` library installed and configured with your API key and base URL.

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://api.naga.ac/v1",
    api_key="YOUR_API_KEY",
)

response = client.responses.create(
    model="gpt-4.1",
    input="Find recent reporting about AI regulation in the UK and cite your sources.",
    tools=[{"type": "web_search"}],
)

print(response.output_text)
```

--------------------------------

### Streaming Response Start of Thinking Block

Source: https://docs.naga.ac/api/messages/thinking-blocks

Shows the initial JSON payload for a streamed thinking block, indicating the start of a thinking content block.

```json
{
  "type": "content_block_start",
  "content_block": {
    "type": "thinking",
    "thinking": ""
  }
}
```

--------------------------------

### Chat Completion with Tool Calling

Source: https://docs.naga.ac/api-reference/chat-completions/create-a-chat-completion

This example demonstrates how to enable tool calling for chat completions. The model can decide to call a function based on the user's request and provided tool definitions.

```json
{
  "model": "gpt-4.1-mini",
  "messages": [
    { "role": "user", "content": "What is the weather in Berlin and should I bring an umbrella?" }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Look up current weather for a city.",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string"
            },
            "unit": {
              "type": "string",
              "enum": ["c", "f"]
            }
          },
          "required": ["city"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}
```

--------------------------------

### Mid-Stream Error Payload Example

Source: https://docs.naga.ac/build/error-handling

Streaming APIs may return errors within the stream after an initial '200 OK'. This example shows the structure of such an error payload.

```json
{
  "error": {
    "type": "inappropriate_content",
    "message": "We got a bad response from the source. Status 403. Error message: Unable to show the generated image."
  }
}
```

--------------------------------

### Check Account Balance (Node.js)

Source: https://docs.naga.ac/account/account-management

This Node.js snippet demonstrates how to fetch your account balance using the fetch API. Replace 'YOUR_PROVISIONING_KEY' with your actual provisioning key.

```javascript
const response = await fetch('https://api.naga.ac/v1/account/balance', {
  headers: {
    Authorization: 'Bearer YOUR_PROVISIONING_KEY',
  },
});

if (!response.ok) {
  throw new Error(`Request failed: ${response.status}`);
}

const data = await response.json();
console.log(data.balance);
```

--------------------------------

### Example Structured Response Shape

Source: https://docs.naga.ac/api/responses/structured-outputs

This is an example of the JSON response structure when requesting structured output. The actual structured data is found within the `content` array as a `text` object.

```json
{
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "output_text",
      "text": "{\"name\":\"Science Fair\",\"date\":\"Friday\",\"participants\":[\"Alice\",\"Bob\"]}",
      "annotations": [],
      "logprobs": []
    }
  ]
}
```

--------------------------------

### Assistant Tool Use Block Example

Source: https://docs.naga.ac/api/messages/tool-use

This JSON represents a tool_use content block returned by the assistant. It specifies the tool name and the input arguments for that tool.

```json
{
  "type": "tool_use",
  "id": "call_1",
  "name": "lookup_weather",
  "input": {
    "city": "Prague"
  }
}
```

--------------------------------

### Example Usage Shape

Source: https://docs.naga.ac/api/images

The Images API response includes a 'usage' object that tracks token consumption for generated images. This example shows the typical structure of the usage data.

```json
{
  "usage": {
    "input_tokens": null,
    "output_tokens": 1536,
    "total_tokens": 1536
  }
}
```

--------------------------------

### Node.js: Initiate Web Search Request

Source: https://docs.naga.ac/api/responses/web-search

In Node.js, include `tools: [{ type: 'web_search' }]` in your `client.responses.create` call to enable web search. This allows the model to access real-time web information for its responses.

```javascript
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.naga.ac/v1',
  apiKey: 'YOUR_API_KEY',
});

const response = await client.responses.create({
  model: 'gpt-4.1',
  input: 'Find recent reporting about AI regulation in the UK and cite your sources.',
  tools: [{ type: 'web_search' }],
});

console.log(response.output_text);
```

--------------------------------

### Image Example

Source: https://docs.naga.ac/api/chat-completions/multimodal-content

This example demonstrates how to send a text message along with an image URL to the Chat Completions API. The `content` field accepts an array of typed content blocks, including `text` and `image_url`.

```APIDOC
## Chat Completions with Image

### Description
This example shows how to send a text message and an image URL within the `messages` array to the Chat Completions API for multimodal processing.

### Method
POST

### Endpoint
/v1/chat/completions

### Request Body
- **model** (string) - Required - The model to use for the chat completion.
- **messages** (array) - Required - An array of message objects, where each message can contain multimodal content.
  - **role** (string) - Required - The role of the author of the message (e.g., "user", "assistant").
  - **content** (array) - Required - An array of content blocks. Each block can be of type `text`, `image_url`, `file`, or `input_audio`.
    - **type** (string) - Required - The type of the content block (e.g., "text", "image_url").
    - **text** (string) - Required if type is "text" - The text content.
    - **image_url** (object) - Required if type is "image_url" - An object containing the image URL and detail level.
      - **url** (string) - Required - The URL of the image (http, https, or data URI).
      - **detail** (string) - Optional - The level of detail for image analysis (`auto`, `low`, `high`). Defaults to `auto`.

### Request Example (Python)
```python
from openai import OpenAI

client = OpenAI(
    base_url="https://api.naga.ac/v1",
    api_key="YOUR_API_KEY",
)

completion = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Describe this image briefly."},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/receipt.png",
                        "detail": "auto",
                    },
                },
            ],
        }
    ],
)

print(completion.choices[0].message.content)
```

### Request Example (Node.js)
```javascript
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.naga.ac/v1',
  apiKey: 'YOUR_API_KEY',
});

const completion = await client.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'Describe this image briefly.' },
        {
          type: 'image_url',
          image_url: {
            url: 'https://example.com/receipt.png',
            detail: 'auto',
          },
        },
      ],
    },
  ],
});

console.log(completion.choices[0].message.content);
```

### Request Example (cURL)
```bash
curl https://api.naga.ac/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d 
    {
      "model": "gpt-4o-mini",
      "messages": [
        {
          "role": "user",
          "content": [
            { "type": "text", "text": "Describe this image briefly." },
            {
              "type": "image_url",
              "image_url": {
                "url": "https://example.com/receipt.png",
                "detail": "auto"
              }
            }
          ]
        }
      ]
    }
```

### Response
#### Success Response (200)
- **choices** (array) - An array of completion choices.
  - **message** (object) - The message content from the model.
    - **content** (string) - The text content of the message.
```
Tokens:
Raw