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://api.lumyx-ai.site/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://api.lumyx-ai.site/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.

memory optional boolean

Enable AI memory for context-aware responses. When enabled, the AI will recall relevant information from past conversations and learn from the current exchange. Default: false

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.