API Reference

Chat Completions

Given a list of messages comprising a conversation, the model will return a response. This endpoint supports both single messages and multi-turn conversations.

Download README

POST https://novaaiapi.nabzclan.vip/v1/chat/completions

Billing & Credits

This endpoint requires a positive account balance. Costs are calculated based on token usage and deducted from your account. If your balance is insufficient, you will receive a 402 Payment Required error.

Conversation History & Logging

To save conversation history and use the conversation_id parameter for multi-turn chats, you must enable Detailed Logging in your API Key settings. If disabled, chats are stateless and won't be saved.

Quick Example

Request

curl -X POST https://novaaiapi.nabzclan.vip/v1/chat/completions \
  -H "Authorization: Bearer nova_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nova_1_1",
    "messages": [
      {
        "role": "user",
        "content": "Write a haiku about programming"
      }
    ],
    "temperature": 0.7,
    "max_tokens": 100
  }'

Request Parameters

model required string

ID of the model to use. Options include: nova_1_1 (standard), nova_2_0 (advanced reasoning), nova_2_1 (code generation).

messages required array

A list of messages comprising the conversation. Each message must have role ("user" or "assistant") and content.

temperature optional number

Sampling temperature between 0 and 2. Higher values = more random. Default: 0.7

max_tokens optional integer

Maximum tokens to generate. Default is model capacity.

max_completion_tokens optional integer

For reasoning models (o1/R1), use this instead of max_tokens. Includes both reasoning and visible content.

reasoning optional object

Unified reasoning configuration for thinking models. Contains:

effort - Reasoning depth: xhigh, high, medium, low, minimal, none (for o1/o3, Grok)
max_tokens - Max reasoning tokens (for Claude, Gemini thinking)
exclude - If true, reasoning is not returned in response
enabled - Enable reasoning with default settings

reasoning_effort optional (legacy) string

Deprecated: Use reasoning.effort instead. Values: low, medium, high. Automatically converted to new format.

stream optional boolean

If true, responses are sent as Server-Sent Events (SSE). Default: false

stream_options optional object

Streaming options. Set include_usage: true to receive token usage stats in the final chunk.

conversation_id optional string

UUID of an existing conversation to continue. If not provided, a new conversation is created.

tools optional array

OpenAI-compatible tool definitions. Tools are passed through when included; no separate model flag is required. Built-in web search uses nabz_search via Nabz Search. Do not use an /extract endpoint for web search.

{
  "type": "function",
  "function": {
    "name": "nabz_search",
    "description": "Search the internet with Nabz Search for current, real-time information.",
    "parameters": {
      "type": "object",
      "properties": {
        "query": {"type": "string"},
        "count": {"type": "integer", "minimum": 1, "maximum": 10, "default": 5}
      },
      "required": ["query"]
    }
  }
}

tool_choice optional string|object

Controls which tool is called. Supports OpenAI-compatible values such as auto, none, or a specific function.

parallel_tool_calls optional boolean

Controls whether the model may call multiple tools in parallel.

Search Strategy

For questions that ask to search, find updates, check latest news, or need fresh info, use nabz_search first, then answer from the returned sources.

Recommended flow

Classify the user request → build a focused query → call nabz_search → read/fetch the top results as needed → answer with sources. Do not call /extract.

Company/update query: include company/project name + “updates”, “news”, “release”, or current year.
Example user ask: hey search for nabzclan new updates
Good query: NabzClan latest updates news releases 2026
Fetch/read: use the URLs returned by search results for context before final answer.
Answer: summarize what changed, include dates if available, cite source URLs.

Tool call example

{
  "tool_choice": "auto",
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "nabz_search",
        "description": "Search the internet with Nabz Search for current, real-time information.",
        "parameters": {
          "type": "object",
          "properties": {
            "query": {"type": "string"},
            "count": {"type": "integer", "minimum": 1, "maximum": 10, "default": 5}
          },
          "required": ["query"]
        }
      }
    }
  ],
  "messages": [
    {"role": "user", "content": "hey search for nabzclan new updates"}
  ]
}

Response Format

Example Response

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1699896916,
  "model": "nova_1_1",
  "context_left": 1998379,
  "context_total": 2000000,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Code flows like water,\nBugs dance in morning debug,\nCoffee solves all things.",
        "tool_calls": null,
        "reasoning_content": null
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 19,
    "total_tokens": 31
  }
}

Vision Support

Vision-enabled models can process both text and images. Images must be provided as base64 encoded strings in data URL format.

Vision Request

{
  "model": "nova_1_1",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What's in this image?"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQE..."
          }
        }
      ]
    }
  ]
}

Image Requirements

Images can be base64 encoded (data URL format) or hosted URLs. Local URLs are automatically converted to base64 before being sent to the AI model.

PDF & File Support

Models with PDF support can process document files using the file content type.

PDF Request

{
  "model": "nova_1_1",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Summarize this document"
        },
        {
          "type": "file",
          "file": {
            "filename": "document.pdf",
            "file_data": "https://example.com/document.pdf"
          }
        }
      ]
    }
  ]
}

Thinking / Reasoning Models

Models that support reasoning (like o1, o3, Claude 3.7 Sonnet, DeepSeek R1) expose their "thinking" process. Use the reasoning parameter to control this behavior.

Reasoning Request

{
  "model": "deepseek-r1",
  "messages": [
    {
      "role": "user",
      "content": "What is 25 * 4?"
    }
  ],
  "reasoning": {
    "effort": "high",
    "max_tokens": 8000
  }
}

Reasoning Response

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "25 * 4 = 100",
        "reasoning": "Let me calculate this step by step...",
        "reasoning_content": "Let me calculate this step by step...",
        "reasoning_details": [
          {
            "type": "reasoning.text",
            "text": "Let me calculate this step by step..."
          }
        ]
      },
      "finish_reason": "stop"
    }
  ]
}

Reasoning Fields

reasoning - Full reasoning text (new format)
reasoning_content - Same as reasoning (legacy compatibility)
reasoning_details - Structured array with reasoning chunks

Error Responses

Status Code	Description
`400 Bad Request`	Invalid request parameters
`401 Unauthorized`	Invalid or missing API key
`429 Too Many Requests`	Rate limit exceeded
`500 Internal Server Error`	Server error

For detailed error handling guidance, see the error handling documentation.