README

xAI PHP SDK

An unofficial PHP SDK for xAI's APIs

The xAI PHP SDK is a modern PHP library for interacting with xAI's APIs. Built for PHP 8.4 and above, it provides full parity with the official Python SDK, offering an intuitive and developer-friendly interface.

Whether you're generating text, images, or structured outputs, the xAI PHP SDK is designed to be robust, type-safe, and production-ready.

Documentation

Comprehensive API documentation is available at docs.x.ai. Explore detailed guides, API references, and tutorials to get the most out of the xAI SDK.

Installation

Install via Composer:

composer require displace/xai-sdk-php

Requirements

• PHP 8.4 or higher
• ext-json extension
• ext-mbstring extension

Quick Start

Client Instantiation

The SDK looks for the XAI_API_KEY environment variable by default:

<?php

use Displace\XaiSdk\XaiClient;

// Uses XAI_API_KEY environment variable
$client = new XaiClient();

// Or explicitly pass the API key
$client = new XaiClient(apiKey: 'your-api-key');

Multi-Turn Chat

The SDK supports multi-turn conversations with a simple append method to manage conversation history:

<?php

use Displace\XaiSdk\XaiClient;
use function Displace\XaiSdk\Chat\system;
use function Displace\XaiSdk\Chat\user;

$client = new XaiClient();

$chat = $client->chat->create(
    model: 'grok-3',
    messages: [
        system('You are a helpful assistant.'),
    ]
);

// Interactive chat loop
while (true) {
    echo "You: ";
    $prompt = trim(fgets(STDIN));

    if (strtolower($prompt) === 'exit') {
        break;
    }

    $chat->append(user($prompt));
    $response = $chat->sample();

    echo "Grok: {$response->getContent()}\n";
    $chat->append($response);
}

Streaming

Stream responses in real-time for interactive applications:

<?php

use Displace\XaiSdk\XaiClient;
use function Displace\XaiSdk\Chat\user;

$client = new XaiClient();
$chat = $client->chat->create(model: 'grok-3');

$chat->append(user('Explain quantum computing in simple terms.'));

echo "Grok: ";
foreach ($chat->stream() as [$response, $chunk]) {
    echo $chunk->content;
}
echo "\n";

// Append the final response to continue the conversation
$chat->append($response);

Image Understanding

Analyze images with vision models:

<?php

use Displace\XaiSdk\XaiClient;
use function Displace\XaiSdk\Chat\image;
use function Displace\XaiSdk\Chat\user;

$client = new XaiClient();
$chat = $client->chat->create(model: 'grok-2-vision');

$chat->append(
    user(
        'What do these images have in common?',
        image('https://example.com/image1.jpg', 'high'),
        image('https://example.com/image2.jpg', 'high')
    )
);

$response = $chat->sample();
echo "Grok: {$response->getContent()}\n";

Features

The xAI PHP SDK provides comprehensive feature coverage:

Configuration

Client Options

<?php

use Displace\XaiSdk\XaiClient;

$client = new XaiClient(
    apiKey: 'your-api-key',           // API key (or use XAI_API_KEY env var)
    baseUrl: 'https://api.x.ai/v1',   // API base URL
    timeout: 120,                      // Request timeout in seconds
);

Chat Configuration

<?php

$chat = $client->chat->create(
    model: 'grok-3',                   // Model to use
    messages: [...],                   // Initial messages
    temperature: 0.7,                  // Sampling temperature (0.0-2.0)
    maxTokens: 1024,                   // Maximum tokens in response
    topP: 0.9,                         // Nucleus sampling parameter
    frequencyPenalty: 0.0,             // Frequency penalty (-2.0-2.0)
    presencePenalty: 0.0,              // Presence penalty (-2.0-2.0)
    tools: [...],                      // Tool/function definitions
    responseFormat: [...],             // Structured output schema
    reasoningEffort: 'high',           // For reasoning models: 'low' or 'high'
);

Environment Variables

Telemetry & Observability

The SDK includes optional OpenTelemetry integration for monitoring and debugging:

Console Export (Development)

<?php

use Displace\XaiSdk\Telemetry\Telemetry;
use Displace\XaiSdk\XaiClient;

$telemetry = new Telemetry();
$telemetry->setupConsoleExporter();

$client = new XaiClient();
// All API calls will now emit traces to the console

OTLP Export (Production)

<?php

use Displace\XaiSdk\Telemetry\Telemetry;

$telemetry = new Telemetry();
$telemetry->setupOtlpExporter(
    endpoint: 'https://your-observability-platform.com/traces',
    headers: ['Authorization' => 'Bearer your-token'],
);

Installation Requirements

# For telemetry support
composer require open-telemetry/sdk

# For OTLP export
composer require open-telemetry/exporter-otlp

Error Handling

The SDK provides typed exceptions for different error scenarios:

<?php

use Displace\XaiSdk\Exceptions\AuthenticationException;
use Displace\XaiSdk\Exceptions\RateLimitException;
use Displace\XaiSdk\Exceptions\ApiException;
use Displace\XaiSdk\Exceptions\XaiException;

try {
    $response = $chat->sample();
} catch (AuthenticationException $e) {
    // Invalid or missing API key
    echo "Authentication failed: {$e->getMessage()}\n";
} catch (RateLimitException $e) {
    // Rate limit exceeded - implement backoff
    echo "Rate limited. Retry after: {$e->getRetryAfter()} seconds\n";
} catch (ApiException $e) {
    // API returned an error
    echo "API error ({$e->getHttpStatusCode()}): {$e->getMessage()}\n";
} catch (XaiException $e) {
    // Base exception for all SDK errors
    echo "Error: {$e->getMessage()}\n";
}

Available Models

Use the Models API to retrieve available models:

<?php

$models = $client->models->list();

foreach ($models as $model) {
    echo "{$model->id}: {$model->description}\n";
}

Development

Running Tests

# Run all tests
composer test

# Run with coverage
composer test:coverage

# Run only unit tests
composer test:unit

Code Quality

# Check code style (PSR-12)
composer cs:check

# Fix code style issues
composer cs:fix

# Run static analysis (PHPStan level 8)
composer stan

# Run all quality checks
composer qa

Comparison with Python SDK

The PHP SDK maintains API parity with the official Python SDK:

PHP-Specific Adaptations

1. Synchronous Only (v1.0) - Async support planned for v2.0
2. REST API - Uses REST with JSON instead of gRPC
3. Iterator Pattern - Uses PHP iterators for streaming
4. Strict Types - Leverages PHP 8.4+ readonly properties

License

The xAI PHP SDK is distributed under the Apache License 2.0.

Copyright 2026 Displace Technologies, LLC

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Attribution

This SDK was inspired by and maintains API compatibility with X.AI LLC's official Python SDK for the xAI API. We thank X.AI LLC for their excellent work on the original SDK design.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Support

• Issues: GitHub Issues
• Documentation: docs.x.ai
• Examples: /examples directory