Grok API: First Query in Ten Minutes, Step by Step

👁 117 reads

Your first query to the Grok API takes four steps and about ten minutes, half of which goes to setting up an account. We walked through the official guide step by step and documented it along with things scattered across five pages of documentation that can stop you on first approach.

Step 1. Account and Credits

You create an account in the console at console.x.ai. The account alone is not enough - the documentation states explicitly that you need to fund it with credits to start using the API. Billing is pay-as-you-go with no minimum amount.

It’s worth knowing the cost right away to choose your first funding amount: Grok 4.7 costs $2 per million input tokens and $6 per million output tokens. A few dollars is enough for weeks of experimentation.

Step 2. API Key

You create the key on the keys page in the console, then set it as an environment variable:

export XAI_API_KEY="your_key"

Or add it to a .env file in your project directory:

XAI_API_KEY=your_key

A rule worth adopting from day one: the key never goes into code or into a repository. Environment variable or a .env file added to .gitignore - that’s it. A key pushed to a public repository is found by bots within minutes, and the bill for someone else’s usage goes to your card.

Step 3. Library

The provider gives you a choice in four variants: their own library for Python and JavaScript, plus variants compatible with the OpenAI interface for both languages.

pip install xai-sdk

When to choose which:

The last row isn’t obvious, so let me expand: the documentation notes that not all tools work in both interfaces. With the gRPC interface in the Python library, the code_interpreter and file_search tools are not supported, though in the newer response interface all tools work. If you’re planning to run code or search files, check this before you write half an application.

Step 4. First Query

Example straight from the provider’s documentation, in Python:

import os
from xai_sdk import Client
from xai_sdk.chat import user

client = Client(api_key=os.getenv("XAI_API_KEY"))
chat = client.chat.create(model="grok-4.7")
chat.append(user("Write a function to validate email addresses and ten tests for it"))
print(chat.sample().content)

That’s all. If this worked, you have a working connection and can move on to harder things - multi-turn conversations, structured output, and streaming.

Image Generation - Also Four Lines

import os, xai_sdk
client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))
response = client.image.sample(
    prompt="A futuristic city skyline at sunset",
    model="grok-imagine-image-2.0",
)
print(response.url)

The image model is a separate name and separate pricing - from $0.04 per image in the 1K variant. We collected practical tips for prompts in our article on image generation.

Five Things That Surprise You on First Approach

1. The model doesn’t know current events. The documentation states this explicitly: without search tools enabled, the model has no knowledge beyond training data. Grok 4.7’s knowledge cutoff date is May 2026. If you’re asking about something more recent, you need to enable web search or X search.
2. Model names have aliases. The plain name points to the latest stable version, the variant with a suffix meaning latest - simply the latest, and the name with a date - a specific release that won’t change. For production where repeatability matters, use the version with a date.
3. Role order is flexible. There’s no requirement for the system message to go first - you can mix roles in any order.
4. The logprobs fields don’t work in models 4.20 and newer. They don’t throw an error - they’re silently ignored. This is the worst kind of incompatibility because the code runs but the result is different than you expect.
5. Input images have limits: maximum 20 MiB per file, only jpg and png. The number of images in a query is not limited, and text and image order is flexible.

What You Can Enable Next

After your first query, it’s worth knowing what else is in the platform, because it, not just the model, determines how much you can build:

On top of that come tokens consumed by the tool itself. We break down the full billing for server-side tools in a separate article, because that’s where most billing surprises happen.

Frequently Asked Questions

How do I start using the Grok API?

Create an account in the console, fund it with credits, generate a key, set it as an environment variable, and install the library. Your first query is four lines of code.

Is the Grok API compatible with OpenAI?

Yes, the provider offers variants compatible with that interface for Python and JavaScript. You don’t need to rewrite existing code.

What is the model called in the API?

grok-4.7. For images grok-imagine-image-2.0, for video grok-imagine-video-1.5.

Is there a free API tier?

The documentation mentions funding the account with credits before starting work. Billing is pay-as-you-go with no minimum amount.

Why doesn’t the model know today’s news?

Because without search tools enabled, it works only on training data, which ends in May 2026. Enable web or X search.

Which model name should I choose for production?

The version with a release date. Aliases update automatically to newer versions, which in production can change behavior without your knowledge.

Kinetyra