Developer documentation

Build with
Lucas AI.

Generate text, extract structured data, and build semantic search with a single API.

response.json 200 OK
{
  "id": "chat_8fd93e",
  "model": "lucas-1-mini",
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "They’re mostly made of ice."
    },
    "finish_reason": "stop"
  }]
}
Base URL https://api.lucasai.cc/v1

Quickstart

Send a message to lucas-1-mini and read the reply from choices[0].message.content.

  1. Authenticate

    Pass a bearer token in the Authorization header. Store the token on your server when building a web app.

  2. Send a message

    Include a model ID and an array of messages with role and content.

  3. Read the reply

    Check for HTTP 200 before reading the generated text. See Errors and retries for other statuses.

These examples use placeholder credentials and sample responses.

curl https://api.lucasai.cc/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "lucas-1-mini",
    "messages": [{
      "role": "user",
      "content": "What are Saturn’s rings made of?"
    }]
  }'

Integration guides

Display replies as they arrive, turn free text into JSON, or find documents by meaning.

Stream a reply

Set stream to true on a chat request to receive server-sent events. Append each choices[0].delta.content fragment to the same message.

Event stream excerpt
data: {"choices":[{"delta":{"content":"Saturn"}}]}

data: {"choices":[{"delta":{"content":" has rings."}}]}

data: [DONE]

Stop reading when you receive [DONE]. A chunk can contain metadata without a text fragment.

Chat completion reference

Extract structured data

Request a JSON object and specify which fields you expect in the prompt. For a support ticket, ask for a category and priority.

Decoded message content
{
  "category": "billing",
  "priority": "high"
}

Set response_format.type to json_object, parse the returned message string, and validate the fields before using them.

Chat request parameters

Search by meaning

Embed document chunks and store each vector with its document ID. Embed search queries with the same model so their vectors can be compared.

Embeddings request body
{
  "model": "lucas-embed-1",
  "input": [
    "Restart a service",
    "Rotate an API token"
  ]
}

Rank the vectors by cosine similarity to the query and return the matching documents.

Embeddings reference

Models

Use a model ID in the model field of your request.

Lucas 1

Multi-step reasoning, long-form writing, and extracting structured data.

lucas-1
Context window
128,000 tokens
Max output
8,192 tokens

Lucas 1 Mini

Short replies, summarization, and everyday classification tasks.

lucas-1-mini
Context window
32,000 tokens
Max output
4,096 tokens

Lucas Embed 1

Text vectors for ranking results, clustering, and semantic search.

lucas-embed-1
Max input per item
8,192 tokens
Vector dimensions
768

For chat models, the context window includes the input messages and generated output. Set max_tokens to budget for the reply. List models via the API

API reference

All paths are relative to https://api.lucasai.cc/v1.

Request headers

Authorization required
Send Bearer YOUR_API_KEY on each request.
Content-Type required for POST
Use application/json for a JSON request body.
View HTTP status codes
POST/chat/completions

Create a chat completion

Generate an assistant reply from a list of messages.

model string · required
lucas-1 or lucas-1-mini.
messages array · required
Ordered messages with text content and a system, user, or assistant role.
max_tokens integer · optional
Maximum number of generated tokens, within the model’s output limit.
stream boolean · default false
Use true to receive partial responses as server-sent events.
response_format object · optional
Use {"type":"json_object"} for a JSON object inside the message content.

Response

In a non-streaming response, read choices[0].message.content for the generated text. A finish_reason of length means the reply reached its token budget. usage reports the input and output token counts.

200 · application/json
{
  "id": "chat_8fd93e",
  "model": "lucas-1-mini",
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "They’re mostly made of ice."
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 8,
    "total_tokens": 26
  }
}
POST/embeddings

Create embeddings

Convert text into numeric vectors for retrieval, ranking, or clustering.

model string · required
Use lucas-embed-1.
input string or array · required
One string or an array of strings, with up to 8,192 tokens per item.

Response

Each entry in data contains a vector and a zero-based index that matches the input position. The sample vector is shortened for readability.

200 · application/json
{
  "model": "lucas-embed-1",
  "data": [{
    "index": 0,
    "embedding": [0.0241, -0.0173, 0.0368]
  }]
}
GET/models

List models

Retrieve the available model IDs. Send this request with the authentication header.

Response

Each entry in data contains an id you can send in the model field.

200 · application/json
{
  "object": "list",
  "data": [
    {"id": "lucas-1", "object": "model"},
    {"id": "lucas-1-mini", "object": "model"},
    {"id": "lucas-embed-1", "object": "model"}
  ]
}

Errors and retries

Use the HTTP status to choose how to handle a failed request. Read error.code to identify the specific error.

StatusMeaning and next step
400Invalid requestCheck required fields, JSON syntax, and the model’s token limit.
401Authentication failedVerify the bearer token before sending another request.
404Resource unavailableCheck the URL or look up the model ID in the catalog.
429Rate limit exceededReduce concurrent requests and wait before retrying.
503Service unavailableRetry after a delay. Handle repeated failures in your app.
429 · application/json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Try again shortly."
  }
}

Retry timing. Honor Retry-After when present. Otherwise, use exponential backoff with a small random delay and cap the number of attempts.