AsyncOpenAI with httpx.Timeout

The OpenAI SDK Alternative

The native xAI SDK isn’t your only option for asynchronous work with the Grok API. The OpenAI SDK, widely adopted across the Python ecosystem, works with the xAI API due to format compatibility. This approach lets you reuse existing OpenAI code and tap into the surrounding tool ecosystem.

Configure AsyncOpenAI for xAI

Initialization requires three parameters: your API key, the xAI base URL, and a timeout adjusted for reasoning models:

from openai import AsyncOpenAI
import httpx

client = AsyncOpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1",
    timeout=httpx.Timeout(3600.0)
)

The key detail here is httpx.Timeout(3600.0). The OpenAI SDK uses httpx as its underlying HTTP client, and the default timeout is 10 minutes. For Grok reasoning models, you need to increase this to 3600 seconds (one hour) to prevent premature disconnections.

Understand httpx.Timeout

The httpx.Timeout class accepts several parameters that control different phases of the connection:

# Uniform timeout: 3600s for everything
timeout = httpx.Timeout(3600.0)

# Granular timeout
timeout = httpx.Timeout(
    connect=10.0,    # initial connection timeout
    read=3600.0,     # response read timeout
    write=30.0,      # request send timeout
    pool=10.0        # wait time for a free connection
)

In production, you can fine-tune these values. The initial connection should fail quickly if the server is unreachable (10 seconds is sufficient), while the read timeout needs to be patient enough to wait for the model’s reasoning.

Send Requests

The syntax follows the standard OpenAI SDK format, using await:

import asyncio

async def query_grok(prompt: str) -> str:
    response = await client.chat.completions.create(
        model="grok-4.20-0309-reasoning",
        messages=[{"role": "user", "content": prompt}]
    )
    return response.choices[0].message.content

result = asyncio.run(query_grok("What are the advantages of Rust over C++?"))

You’ll see the same structure as the OpenAI API: a messages array with roles and content. The response follows the same schema, accessible via response.choices[0].message.content.

Error Handling with httpx

The OpenAI SDK with httpx provides specific exceptions that you need to catch:

from openai import APITimeoutError, APIConnectionError, RateLimitError

async def safe_query(prompt: str) -> str | None:
    try:
        response = await client.chat.completions.create(
            model="grok-4.20-0309-reasoning",
            messages=[{"role": "user", "content": prompt}]
        )
        return response.choices[0].message.content
    except APITimeoutError:
        print("Timeout exceeded—request took too long")
        return None
    except RateLimitError:
        print("Rate limit reached—slow down requests")
        return None
    except APIConnectionError:
        print("Cannot connect to xAI server")
        return None

The three most common exceptions are APITimeoutError (the model didn’t respond within the allotted time), RateLimitError (you exceeded RPM/TPM limits), and APIConnectionError (network issue).

When to Choose AsyncOpenAI Over the xAI SDK

The OpenAI SDK is preferable if you already have an OpenAI codebase, use third-party tools compatible with OpenAI (LangChain, LiteLLM), or want to switch between providers without modifying your code. The native xAI SDK, however, offers more direct access to Grok-specific features, such as built-in tools.

Key Takeaways

• AsyncOpenAI works with the xAI API via base_url="https://api.x.ai/v1"
• httpx.Timeout(3600.0) is required for reasoning models
• Request and response format is identical to the standard OpenAI API
• Exceptions APITimeoutError, RateLimitError, and APIConnectionError cover the main error cases
• This choice is ideal for reusing existing code or integrating third-party tools compatible with OpenAI