Grok API Documentation: Complete Integration Guide

The quickest way to integrate the Grok API is to send an OpenAI-compatible Chat Completions request. With Sublyx, the base URL is https://api.sublyx.org/v1, authentication uses a Sublyx API key, and the selected Grok model is passed in the model field.

Minimal Grok API request

curl https://api.sublyx.org/v1/chat/completions \
  -H "Authorization: Bearer $SUBLYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.5",
    "messages": [
      {"role": "user", "content": "Explain idempotency in two sentences."}
    ]
  }'

Keep API keys on a server, secret manager, or protected development machine. Never put a production key in browser JavaScript, a mobile bundle, a public repository, or an error report.

Endpoint and authentication

Setting	Value	Notes
Base URL	https://api.sublyx.org/v1	Use this value with OpenAI-compatible SDKs.
Endpoint	POST /chat/completions	Creates a text or tool-assisted completion.
Authentication	Authorization: Bearer KEY	Recommended form for the compatible endpoint.
Content type	application/json	Required for JSON request bodies.

A 401 usually means the key is missing, malformed, disabled, or sent to the wrong host. A 402 can indicate insufficient account balance. A 429 indicates a rate or quota constraint, while a 5xx response is normally transient and should be handled with bounded retries.

Grok API request parameters

Parameter	Purpose	Practical guidance
model	Selects the Grok model.	Required. Read the current model ID from the catalog.
messages	Conversation history and instructions.	Required. Use valid roles and keep only relevant history.
temperature	Adjusts sampling variability.	Lower values are usually more repeatable; support and range can vary by model.
top_p	Controls nucleus sampling.	Usually tune either this or temperature, not both at once.
max_tokens	Caps generated output.	Set a business-appropriate limit to control latency and cost.
stream	Returns incremental output events.	Use true for lower perceived latency.
tools	Describes callable functions.	Verify the selected model supports tool calling before relying on it.
tool_choice	Controls whether a tool is selected.	Compatibility can differ across model versions.

OpenAI compatibility does not mean every provider-specific capability is identical. Validate parameter support, tool-call shape, finish reasons, and streaming events against the exact model used in production.

Python example

from openai import OpenAI

client = OpenAI(
    base_url="https://api.sublyx.org/v1",
    api_key="YOUR_SUBLYX_API_KEY",
)

response = client.chat.completions.create(
    model="grok-4.5",
    messages=[
        {"role": "system", "content": "Answer as a concise API engineer."},
        {"role": "user", "content": "What is exponential backoff?"},
    ],
    max_tokens=300,
)

print(response.choices[0].message.content)

Node.js example

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.sublyx.org/v1",
  apiKey: process.env.SUBLYX_API_KEY,
});

const response = await client.chat.completions.create({
  model: "grok-4.5",
  messages: [{ role: "user", content: "Return three caching rules." }],
  max_tokens: 300,
});

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

Streaming Grok responses

Streaming reduces time to first visible output but adds lifecycle work. The client must handle incremental chunks, cancellation, an interrupted connection, and a response that ends before a normal completion marker.

const stream = await client.chat.completions.create({
  model: "grok-4.5",
  messages: [{ role: "user", content: "Explain circuit breakers." }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || "");
}

Do not blindly replay a request after a stream breaks. The model may already have produced billable output. Record the request ID, received content, elapsed time, model, and retry count before deciding whether to restart.

Timeouts, retries and production limits

• Set separate connection, first-token, idle-stream, and total request timeouts where your HTTP client permits it.
• Retry only transient failures such as selected 429 and 5xx responses.
• Use exponential backoff with random jitter and a strict maximum attempt count.
• Do not retry authentication, permission, malformed request, or insufficient-balance errors unchanged.
• Limit concurrency per model instead of allowing every user request to hit the upstream at once.
• Log request IDs and status details, but never log API keys or sensitive prompt content.

See the dedicated Grok API timeout guide for diagnosis by timeout phase. For general quota handling, read the AI API 429 guide.

Grok text API vs Grok Imagine API

The Chat Completions endpoint is for Grok text and tool-assisted workloads. Grok Imagine uses separate media models and asynchronous image endpoints. Image generation submits to /v1/images/generations/async, image editing submits to /v1/images/edits/async, and both use /v1/images/tasks/:task_id for task status.

Do not send grok-imagine-image to Chat Completions or treat an asynchronous media submission as a final image response. The Grok Imagine API guide covers those workflows.

Compatibility and source notes

This guide documents the Sublyx-compatible endpoints verified in this site repository. xAI can add or change native parameters independently. Check the xAI developer documentation for native Grok behavior and the Sublyx console for current model availability before shipping.