API Documentation

All API endpoints require authentication using an API key. Include your API key in the Authorization header:

Authorization: Bearer sk-gateway-xxxxxxxxxxxxx

Get your API key from the API Keys page in your dashboard after creating an account.

Endpoints Overview

Using Different Models

NextcraftAI supports models from multiple providers. Specify the model in the request body using the model field. You can also specify the provider via query parameters or let the routing strategy choose automatically.

Google Gemini Models

OpenAI Models

For complete model listings and pricing information, visit our Models page.

POST /v1/chat/completions

Send chat messages to AI models through a unified interface. Supports multiple providers (Google Gemini, OpenAI, xAI Grok) and intelligent routing strategies.

Request Body

{
  "model": "gemini-pro-2.5",
  "messages": [
    {
      "role": "user",
      "content": "Hello, how are you?"
    }
  ],
  "context": "You are a helpful AI assistant. Always be polite and concise.",
  "temperature": 0.7,
  "max_tokens": 1000
}

Note: The context field is optional and allows you to provide system-level instructions or context that will be prepended as a system message to your conversation. This is useful for setting the AI's behavior, tone, or providing background information.

Code Examples

import requests

response = requests.post(
    'https://api.nextcraftai.com/v1/chat/completions',
    params={'provider': 'gemini'},
    headers={
        'Authorization': 'Bearer sk-gateway-xxxxxxxxxxxxx',
        'Content-Type': 'application/json'
    },
    json={
        'model': 'gemini-pro-2.5',
        'messages': [
            {'role': 'user', 'content': 'Hello, how are you?'}
        ],
        'context': 'You are a helpful AI assistant. Always be polite and concise.',
        'temperature': 0.7,
        'max_tokens': 1000
    }
)

data = response.json()
print(data['choices'][0]['message']['content'])

POST /v1/multichat/completion

Send the same message to multiple AI models simultaneously for side-by-side comparison. Perfect for comparing responses from different models or providers. Supports up to 4 models per request.

Request Body

{
  "models": [
    {
      "model": "gemini-pro-2.5",
      "provider": "gemini"
    },
    {
      "model": "gpt-5.2",
      "provider": "openai"
    }
  ],
  "messages": [
    {
      "role": "user",
      "content": "Explain quantum computing in simple terms"
    }
  ],
  "context": "You are a science educator. Explain complex topics in simple, easy-to-understand language.",
  "temperature": 0.7,
  "max_tokens": 1000
}

Note: The optional context field applies to all models in the multichat request, allowing you to set consistent system-level instructions across all model responses.

The API uses standard HTTP status codes and returns error objects in a consistent format:

{
  "error": {
    "message": "Insufficient wallet balance. Minimum required: $0.10",
    "type": "invalid_request_error"
  }
}

Common Status Codes