xAI API

https://docs.x.ai/developers
Admin
xAI API is a toolkit for developers to programmatically integrate xAI's Grok large language models...
Tokens:428,461
Snippets:2,590
Trust Score:9.5
Update:2 days ago
Show doc for...
Tokens:
Raw
### Response for starting video generation

Source: https://docs.x.ai/developers/model-capabilities/video/generation

Example JSON response from the start request, containing the request_id needed for polling.

```json
{"request_id": "d97415a1-5796-b7ec-379f-4e6819e08fdf"}
```

--------------------------------

### GET /v1/videos/{request_id} - JavaScript example

Source: https://docs.x.ai/developers/rest-api-reference/inference/videos

JavaScript fetch example to retrieve the video generation result. Uses process.env.VIDEO_REQUEST_ID and process.env.XAI_API_KEY.

```JavaScript
const response = await fetch(
  `https://api.x.ai/v1/videos/${process.env.VIDEO_REQUEST_ID}`,
  {
    headers: {
      Authorization: `Bearer ${process.env.XAI_API_KEY}`,
    },
  },
);

console.log(JSON.stringify(await response.json(), null, 2));
```

--------------------------------

### GET /v1/api-key - 200 Response Example

Source: https://docs.x.ai/developers/rest-api-reference/inference/other

Example response for a successful GET /v1/api-key request, showing the API key details.

```json
{
  "redacted_api_key": "xai-...b14o",
  "user_id": "59fbe5f2-040b-46d5-8325-868bb8f23eb2",
  "name": "My API Key",
  "create_time": "2024-01-01T12:55:18.139305Z",
  "modify_time": "2024-08-28T17:20:12.343321Z",
  "modified_by": "3d38b4dc-4eb7-4785-ae26-c3fa8997ffc7",
  "team_id": "5ea6f6bd-7815-4b8a-9135-28b2d7ba6722",
  "acls": [
    "api-key:model:*",
    "api-key:endpoint:*"
  ],
  "api_key_id": "ae1e1841-4326-4b36-a8a9-8a1a7237db11",
  "team_blocked": false,
  "api_key_blocked": false,
  "api_key_disabled": false
}
```

--------------------------------

### Python: Complete workflow for using files with Grok

Source: https://docs.x.ai/developers/files

Use this Python example with the xai_sdk to reference a public file by URL or upload a file, then chat with files. It includes steps to upload, chat, get the answer, and clean up. Requires an XAI_API_KEY environment variable.

```Python
import os
from xai_sdk import Client
from xai_sdk.chat import user, file

client = Client(api_key=os.getenv("XAI_API_KEY"))

# 1a. Reference a public file by URL
file_url = "https://example-files.online-convert.com/document/txt/example.txt"

# 1b. Or upload a file and reference by ID
uploaded_file = client.files.upload(
    b"Employee: Alice Johnson\nDepartment: Engineering",
    filename="employee.txt",
)

# 2. Chat with files
chat = client.chat.create(model="grok-4.7")
chat.append(user(
    "Summarize both documents",
    file(url=file_url),
    file(uploaded_file.id),
))

# 3. Get the answer
response = chat.sample()
print(response.content)

# 4. Clean up uploaded file
client.files.delete(uploaded_file.id)
```

--------------------------------

### Install Grok Build with curl

Source: https://docs.x.ai/developers/release-notes

Install Grok Build using a single command. This command downloads and runs the installation script from x.ai.

```bash
curl -fsSL https://x.ai/cli/install.sh | bash
```

--------------------------------

### GET /v1/videos/{request_id} - Python example

Source: https://docs.x.ai/developers/rest-api-reference/inference/videos

Python requests example to retrieve the video generation result. Uses environment variables VIDEO_REQUEST_ID and XAI_API_KEY.

```Python
import json
import os

import requests

request_id = os.environ["VIDEO_REQUEST_ID"]

response = requests.get(
    f"https://api.x.ai/v1/videos/{request_id}",
    headers={
        "Authorization": f"Bearer {os.environ['XAI_API_KEY']}",
    },
)

print(json.dumps(response.json(), indent=2))
```

--------------------------------

### GET /v1/videos/{request_id} - Output example

Source: https://docs.x.ai/developers/rest-api-reference/inference/videos

Example JSON output for a completed video generation request, showing status 'done', video URL, duration, respect_moderation, model, usage cost, and progress.

```JSON
{
  "status": "done",
  "video": {
    "url": "https://vidgen.x.ai/xai-vidgen-bucket/xai-video-cb3a83ec-322f-4318-990d-166bab11d328.mp4",
    "duration": 1,
    "respect_moderation": true
  },
  "model": "grok-imagine-video",
  "usage": {
    "cost_in_usd_ticks": 500000000
  },
  "progress": 100
}
```

--------------------------------

### Example response for GET /v1/images/{request_id}

Source: https://docs.x.ai/developers/rest-api-reference/inference/images

Example JSON response showing a completed image generation with status 'done', a data array containing the image URL and MIME type, and usage cost in USD ticks.

```json
{
  "request_id": "572d62a8-c2ae-47f6-9c60-21ed08bdcd30",
  "status": "done",
  "data": [
    {
      "url": "https://imgen.x.ai/xai-imgen/xai-tmp-imgen-572d62a8-c2ae-47f6-9c60-21ed08bdcd30-4ba414e5.jpeg",
      "mime_type": "image/jpeg"
    }
  ],
  "usage": {
    "cost_in_usd_ticks": 200000000
  }
}

```

--------------------------------

### Install xAI SDK for Python

Source: https://docs.x.ai/developers/quickstart

Installs the official xAI SDK for Python.

```bash
pip install xai-sdk

```

--------------------------------

### Install required packages

Source: https://docs.x.ai/developers/community/microsoft-foundry

Install the OpenAI SDK and Azure Identity package for authentication. This is the primary installation command for using Grok models on Foundry.

```bash
pip install -U openai azure-identity

```

--------------------------------

### Install OpenAI JavaScript SDK

Source: https://docs.x.ai/developers/quickstart

Installs the OpenAI JavaScript SDK for use with the xAI API.

```bash
npm install openai

```

--------------------------------

### Get custom voice - example response

Source: https://docs.x.ai/developers/rest-api-reference/inference/voice

Example JSON response for a successful GET request, showing the voice metadata fields.

```json
{
  "voice_id": "nlbqfwie",
  "name": "Friendly Narrator",
  "description": "Warm, conversational tone for narration.",
  "gender": "female",
  "accent": "American",
  "age": "young",
  "language": "en",
  "use_case": "narration",
  "tone": "warm",
  "created_at": "2026-04-26T18:56:34.872993+00:00"
}

```

--------------------------------

### Example output - usage counts

Source: https://docs.x.ai/developers/tools/x-search

Shows the expected output from the previous examples, indicating the number of posts and users fetched.

```text
x_posts_fetched: 19
x_users_fetched: 0
```

--------------------------------

### End-to-End Financial Analysis with xai_sdk

Source: https://docs.x.ai/developers/tools/collections-search

This example uses the xai_sdk AsyncClient to create a collection, upload Tesla 10-Q and 10-K PDFs, and run a chat with collections_search and code_execution tools. It streams the response, showing reasoning tokens and tool calls, and prints citations and usage. Requires XAI_API_KEY and XAI_MANAGEMENT_API_KEY environment variables.

```python
import asyncio
import os

import httpx

from xai_sdk import AsyncClient
from xai_sdk.chat import user
from xai_sdk.proto import collections_pb2
from xai_sdk.tools import code_execution, collections_search

TESLA_10_Q_PDF_URL = "https://ir.tesla.com/_flysystem/s3/sec/000162828025045968/tsla-20250930-gen.pdf"
TESLA_10_K_PDF_URL = "https://ir.tesla.com/_flysystem/s3/sec/000162828025003063/tsla-20241231-gen.pdf"
async def main():
    client = AsyncClient(api_key=os.getenv("XAI_API_KEY"), management_api_key=os.getenv("XAI_MANAGEMENT_API_KEY"))

    # Step 1: Create a collection for Tesla SEC filings
    response = await client.collections.create("tesla-sec-filings")
    print(f"Created collection: {response.collection_id}")

    # Step 2: Upload documents to the collection concurrently
    async def upload_document(
        url: str, name: str, collection_id: str, http_client: httpx.AsyncClient
    ) -> None:
        pdf_response = await http_client.get(url, timeout=30.0)
        pdf_content = pdf_response.content

        print(f"Uploading {name} document to collection")
        response = await client.collections.upload_document(
            collection_id=collection_id,
            name=name,
            data=pdf_content,
        )

        # Poll until document is processed and ready for search
        response = await client.collections.get_document(response.file_metadata.file_id, collection_id)
        print(f"Waiting for document {name} to be processed")
        while response.status != collections_pb2.DOCUMENT_STATUS_PROCESSED:
            await asyncio.sleep(3)
            response = await client.collections.get_document(response.file_metadata.file_id, collection_id)

        print(f"Document {name} processed")

    # Upload both documents concurrently
    async with httpx.AsyncClient() as http_client:
        await asyncio.gather(
            upload_document(TESLA_10_Q_PDF_URL, "tesla-10-Q-2024.pdf", response.collection_id, http_client),
            upload_document(TESLA_10_K_PDF_URL, "tesla-10-K-2024.pdf", response.collection_id, http_client),
        )

    # Step 3: Create a chat with collections search enabled
    chat = client.chat.create(
        model="grok-4.7",  # Use a reasoning model for better analysis
        tools=[
            collections_search(
                collection_ids=[response.collection_id],
            ),
            code_execution(),
        ],
        include=["verbose_streaming"],
    )

    # Step 4: Ask a complex analytical question that requires searching multiple documents
    chat.append(
        user(
            "How many consumer vehicles did Tesla produce in total in 2024 and 2025? "
            "Show your working and cite your sources."
        )
    )

    # Step 5: Stream the response and display reasoning progress
    is_thinking = True
    async for response, chunk in chat.stream():
        # View server-side tool calls as they happen
        for tool_call in chunk.tool_calls:
            print(f"\nCalling tool: {tool_call.function.name} with arguments: {tool_call.function.arguments}")
        if response.usage.reasoning_tokens and is_thinking:
            print(f"\rThinking... ({response.usage.reasoning_tokens} tokens)", end="", flush=True)
        if chunk.content and is_thinking:
            print("\n\nFinal Response:")
            is_thinking = False
        if chunk.content and not is_thinking:
            print(chunk.content, end="", flush=True)
        latest_response = response

    # Step 6: Review citations and tool usage
    print("\n\nCitations:")
    print(latest_response.citations)
    print("\n\nUsage:")
    print(latest_response.usage)
    print(latest_response.server_side_tool_usage)
    print("\n\nTool Calls:")
    print(latest_response.tool_calls)
if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### 16-Agent Setup with xai_sdk

Source: https://docs.x.ai/developers/model-capabilities/text/multi-agent

Uses the xai_sdk Python client to create a chat with 16 agents. Streams responses and prints content chunks as they arrive.

```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.20-multi-agent",
    agent_count=16,
)

chat.append(user("Analyze the design trade-offs in modern programming languages: compare Rust's ownership model, Go's simplicity philosophy, and Haskell's pure functional approach. Cover memory safety, concurrency, developer productivity, and ecosystem maturity."))
for response, chunk in chat.stream():
    if chunk.content:
        print(chunk.content, end="", flush=True)

```

--------------------------------

### 4-Agent Setup with xAI SDK (Python)

Source: https://docs.x.ai/developers/model-capabilities/text/multi-agent

Uses the xai_sdk to create a chat with agent_count set to 4 and streams the response. Requires the xai_sdk package and XAI_API_KEY environment variable.

```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.20-multi-agent",
    agent_count=4,
)

chat.append(user("What are the key differences between TCP and UDP?"))
for response, chunk in chat.stream():
    if chunk.content:
        print(chunk.content, end="", flush=True)

```

--------------------------------

### Example server-side tool usage output

Source: https://docs.x.ai/developers/tools/tool-usage-details

Example output showing a dictionary with tool names and counts. This is the format returned by `response.server_side_tool_usage`.

```output
{'SERVER_SIDE_TOOL_X_SEARCH': 3, 'SERVER_SIDE_TOOL_WEB_SEARCH': 2}
```

--------------------------------

### Get TTS voice details - Output JSON

Source: https://docs.x.ai/developers/rest-api-reference/inference/voice

Example JSON response for the get voice endpoint, showing details for the 'eve' voice.

```json
{
  "voice_id": "eve",
  "name": "Eve",
  "language": "multilingual"
}

```

--------------------------------

### SDK Methods: start(), get()

Source: https://docs.x.ai/developers/model-capabilities/video/generation

The xai_sdk provides methods to start a video generation and retrieve its status. The status is returned as a proto enum.

```APIDOC
## SDK Methods: start(), get()

### Description
The xai_sdk provides methods to start a video generation and retrieve its status. The status is returned as a proto enum.

### Methods
#### start(prompt, model, duration)
- **prompt** (string) - Required - The text prompt describing the video.
- **model** (string) - Required - The model to use.
- **duration** (integer) - Required - The duration in seconds.
- **Returns**: An object containing a `request_id` field.

#### get(request_id)
- **request_id** (string) - Required - The ID of the generation request.
- **Returns**: An object with a `status` field (enum) and a `response` field when done.
  - `status` can be `deferred_pb2.DeferredStatus.PENDING`, `deferred_pb2.DeferredStatus.DONE`, or `deferred_pb2.DeferredStatus.FAILED`.
  - When status is DONE, `response.video.url` contains the video URL.

### Status Values
- **deferred_pb2.DeferredStatus.PENDING** - Video is still being generated.
- **deferred_pb2.DeferredStatus.DONE** - Video is ready.
- **deferred_pb2.DeferredStatus.FAILED** - Video generation failed.
```

--------------------------------

### 4-Agent Setup with OpenAI SDK (Python)

Source: https://docs.x.ai/developers/model-capabilities/text/multi-agent

Uses the OpenAI SDK with a custom base URL to call the multi-agent model with reasoning effort 'low'. Requires the openai package and XAI_API_KEY environment variable.

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1",
)

response = client.responses.create(
    model="grok-4.20-multi-agent",
    reasoning={"effort": "low"},
    input=[
        {
            "role": "user",
            "content": "What are the key differences between TCP and UDP?",
        },
    ],
)

print(response.output_text)

```

--------------------------------

### Deferred chat completion response example

Source: https://docs.x.ai/developers/rest-api-reference/inference/chat-completions

Example 200 response for GET /v1/chat/deferred-completion/{request_id}. Shows the completed chat response with usage details.

```json
{
  "id": "335b92e4-afa5-48e7-b99c-b9a4eabc1c8e",
  "object": "chat.completion",
  "created": 1743770624,
  "model": "latest",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "101 multiplied by 3 is 303.",
        "refusal": null
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 31,
    "completion_tokens": 11,
    "total_tokens": 42,
    "prompt_tokens_details": {
      "text_tokens": 31,
      "audio_tokens": 0,
      "image_tokens": 0,
      "cached_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0,
      "audio_tokens": 0,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    }
  },
  "system_fingerprint": "fp_156d35dcaa"
}
```

--------------------------------

### Get TTS voice details with Python requests

Source: https://docs.x.ai/developers/rest-api-reference/inference/voice

Use this Python example to get details for a specific voice. Requires the XAI_API_KEY environment variable.

```python
import json
import os

import requests

voice_id = "eve"

response = requests.get(
    f"https://api.x.ai/v1/tts/voices/{voice_id}",
    headers={
        "Authorization": f"Bearer {os.environ['XAI_API_KEY']}",
    },
)

print(json.dumps(response.json(), indent=2))

```

--------------------------------

### Manage files via Files API with Python

Source: https://docs.x.ai/developers/model-capabilities/imagine/files/outputs

Python example using the xai_sdk to generate an image, then inspect file metadata, revoke the public URL, create a new one with a 7-day expiry, and delete the file. Demonstrates the full lifecycle of files created via storage_options.

```Python
import os
import xai_sdk

client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))

response = client.image.sample(
    prompt="A futuristic city",
    model="grok-imagine-image-2.0",
    storage_options={"filename": "city.jpg", "public_url": True},
)
file_id = response.file_output.file_id

# Inspect file metadata
file = client.files.get(file_id)

# Stop sharing publicly (keeps the file in your storage)
client.files.revoke_public_url(file_id)

# Generate a new public URL later with a different expiry
client.files.create_public_url(file_id, expires_after=604800)  # 7 days

# Delete the file entirely (also tears down any active public URL)
client.files.delete(file_id)
```

--------------------------------

### Get TTS voice details with JavaScript fetch

Source: https://docs.x.ai/developers/rest-api-reference/inference/voice

Use this JavaScript example to get details for a specific voice. Requires the XAI_API_KEY environment variable.

```javascript
const voiceId = "eve";

const response = await fetch(`https://api.x.ai/v1/tts/voices/${voiceId}`, {
  headers: {
    Authorization: `Bearer ${process.env.XAI_API_KEY}`,
  },
});

const data = await response.json();
console.log(JSON.stringify(data, null, 2));

```

--------------------------------

### Install AI SDK for JavaScript

Source: https://docs.x.ai/developers/quickstart

Installs the AI SDK, the xAI provider, and Zod for JavaScript. Required for using the AI SDK with xAI.

```bash
npm install ai @ai-sdk/xai zod

```

--------------------------------

### GET /v1/billing/teams/{team_id}/billing-info - 200 Response

Source: https://docs.x.ai/developers/rest-api-reference/management/billing

Example response for a successful get billing information request. Contains the billingInfo object with fields such as name, address, email, taxIdType, and taxNumber.

```json
{
  "billingInfo": {
    "name": "Acme Inc.",
    "address": {
      "line1": "123 Main St.",
      "line2": "",
      "city": "New York",
      "country": "US",
      "postalCode": "12345",
      "state": "New York"
    },
    "email": "foo@example.com",
    "taxIdType": "us_ein",
    "taxNumber": "12-3456789"
  }
}
```

--------------------------------

### Example output of tool calls

Source: https://docs.x.ai/developers/tools/advanced-usage

Shows the expected output from the tool loop, including a server-side web_search call, a client-side get_weather call, and the final response.

```text
Server-side tool call: web_search with arguments: {"query":"Who won the 2025 NBA championship?","num_results":5}
Client-side tool call: get_weather with arguments: {"city":"Oklahoma City"}
Final response: The Oklahoma City Thunder won the 2025 NBA championship. The current weather in Oklahoma City is sunny.

```

--------------------------------

### Client-side Tools with Structured Output

Source: https://docs.x.ai/developers/model-capabilities/text/structured-outputs

This example sets up a chat with a custom tool that computes Collatz steps, handles tool calls in a loop, and parses the final response into a structured output using a Pydantic model. It requires an XAI_API_KEY environment variable and a CollatzResult schema defined elsewhere.

```python
import os
import json
from pydantic import BaseModel, Field

from xai_sdk import Client
from xai_sdk.chat import tool, tool_result, user

# CollatzResult schema defined above

def collatz_steps(n: int) -> int:
    """Returns the number of steps for n to reach 1 in the Collatz sequence."""
    steps = 0
    while n != 1:
        n = n // 2 if n % 2 == 0 else 3 * n + 1
        steps += 1
    return steps

collatz_tool = tool(
    name="collatz_steps",
    description="Compute the number of steps for a number to reach 1 in the Collatz sequence",
    parameters={
        "type": "object",
        "properties": {
            "n": {"type": "integer", "description": "The starting number"},
        },
        "required": ["n"],
    },
)

client = Client(api_key=os.getenv("XAI_API_KEY"))
chat = client.chat.create(
    model="grok-4.7",
    tools=[collatz_tool],
)

chat.append(user("Use the collatz_steps tool to find how many steps it takes for 20250709 to reach 1."))

# Handle tool calls until we get a final response
while True:
    response = chat.sample()
    
    if not response.tool_calls:
        break
    
    chat.append(response)
    for tc in response.tool_calls:
        args = json.loads(tc.function.arguments)
        result = collatz_steps(args["n"])
        chat.append(tool_result(str(result)))

# Parse the final response into structured output
response, result = chat.parse(CollatzResult)

print(f"Starting number: {result.starting_number}")
print(f"Steps to reach 1: {result.steps}")
```

--------------------------------

### 16-Agent Setup with AI SDK (JavaScript)

Source: https://docs.x.ai/developers/model-capabilities/text/multi-agent

Uses the @ai-sdk/xai package with the 'grok-4.20-multi-agent' model and high reasoning effort. The prompt asks for a comparative analysis of programming languages.

```javascript
import { xai } from "@ai-sdk/xai";
import { generateText } from "ai";

const { text } = await generateText({
  model: xai.responses("grok-4.20-multi-agent"),
  prompt:
    "Analyze the design trade-offs in modern programming languages: compare Rust's ownership model, Go's simplicity philosophy, and Haskell's pure functional approach. Cover memory safety, concurrency, developer productivity, and ecosystem maturity.",
  providerOptions: {
    xai: { reasoningEffort: "high" },
  },
});

console.log(text);

```

--------------------------------

### POST /v1/images/generations - Multiple Outputs

Source: https://docs.x.ai/developers/model-capabilities/imagine/files/outputs

Example of generating multiple images with storage_options and public_url enabled. Each image gets its own file_id and public_url.

```APIDOC
## POST /v1/images/generations

### Description
Generates one or more images based on a prompt. When `n` is greater than 1, each image gets its own `file_id` and `public_url` with a unique token. Files are independent; revoking or deleting one does not affect others.

### Method
POST

### Endpoint
https://api.x.ai/v1/images/generations

### Parameters
#### Request Body
- **model** (string) - Required - The model to use, e.g., "grok-imagine-image-2.0".
- **prompt** (string) - Required - The text prompt describing the image(s) to generate.
- **n** (integer) - Optional - Number of images to generate. Default is 1.
- **response_format** (string) - Optional - Format of the response, e.g., "url".
- **storage_options** (object) - Optional - Storage options for the generated files.
  - **filename** (string) - Required - The filename to use for the stored file.
  - **public_url** (boolean) - Optional - Whether to create a public URL for the file.

### Request Example
```bash
curl -s -X POST https://api.x.ai/v1/images/generations \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0",
    "prompt": "A cat wearing a hat, four different art styles",
    "n": 4,
    "response_format": "url",
    "storage_options": {"filename": "cat-styles.jpg", "public_url": true}
  }'
```

### Response
#### Success Response (200)
Each generated asset includes a `file_output` block with the following fields:
- **file_id** (string) - Always present - Stable Files API identifier. Use for `client.files.*` operations.
- **filename** (string) - Always present - The filename provided in `storage_options`.
- **expires_at** (integer) - Only when file has expiration - Unix timestamp when the file expires.
- **public_url** (string) - Only when `storage_options.public_url` was set and creation succeeded - The permanent shareable URL.
- **public_url_expires_at** (integer) - Only when public URL has expiry - Unix timestamp when the public URL expires. Absent for permanent URLs.
- **public_url_error** (string) - Only on partial failure - Human-readable error when asset stored but public URL creation failed.

#### Response Example
```json
{
  "data": [
    {
      "file_output": {
        "file_id": "file_123",
        "filename": "cat-styles.jpg",
        "public_url": "https://example.com/cat-styles-1.jpg"
      }
    },
    {
      "file_output": {
        "file_id": "file_456",
        "filename": "cat-styles.jpg",
        "public_url": "https://example.com/cat-styles-2.jpg"
      }
    }
  ]
}
```

### Notes
- The Python SDK also surfaces `response.public_url` and `response.public_url_error` as top-level shortcuts on `ImageResponse` and `VideoResponse`.
- When `n > 1`, each image has its own `file_id` and `public_url` with a unique token. Files are independent.
```

--------------------------------

### GET /v1/billing/teams/{team_id}/invoices

Source: https://docs.x.ai/developers/rest-api-reference/management/billing

Retrieves a list of invoices for a specified team. Supports filtering by billing cycle, start date, or invoice IDs.

```APIDOC
## GET /v1/billing/teams/{team_id}/invoices

### Description
Retrieves a list of invoices for a specified team. Supports filtering by billing cycle, start date, or invoice IDs.

### Method
GET

### Endpoint
/v1/billing/teams/{team_id}/invoices

### Parameters
#### Path Parameters
- **team_id** (string) - Required - Team ID of the team.

#### Query Parameters
- **billingCycle.year** (integer) - Optional - Year of the billing cycle.
- **billingCycle.month** (integer) - Optional - Month of the billing cycle.
- **since.year** (integer) - Optional - Year of the start date.
- **since.month** (integer) - Optional - Month of the start date.
- **invoiceIds.invoiceIds** (array) - Optional - List of invoice IDs to filter by.

### Request Example
No parameters.

### Response
#### Success Response (200)
- **invoices** (array) - Invoices.

#### Response Example
{
  "invoices": [
    {
      "teamId": "65c1e471-205f-4566-9c5a-07198bcdf4ce",
      "invoiceId": "aUa1nsnCQfxOFnWjqdimZczKKNJJ5xuwlkb-k0XiUOQ=",
      "invoiceNumber": "742-250-927-721",
      "createTime": "2025-04-01T21:19:48.569466Z",
      "invoiceStatus": "PAID",
      "firstDesiredNextCycleTs": "2025-04-11T02:46:58Z",
      "chargerAttempts": [
        {
          "ticket": 0,
          "successful": false,
          "paymentMethodId": ""
        },
        {
          "ticket": 1,
          "successful": true,
          "paymentMethodId": ""
        }
      ],
      "lines": [
        {
          "clusterName": "us-east-1",
          "description": "Chat grok-2-1212-1.0.0",
          "unitType": "Prompt text tokens",
          "unitPrice": "20000",
          "numUnits": "908",
          "amount": "0"
        },
        {
          "clusterName": "us-east-1",
          "description": "Chat grok-2-1212-1.0.0",
          "unitType": "Completion text tokens",
          "unitPrice": "100000",
          "numUnits": "534",
          "amount": "0"
        }
      ],
      "subtotal": "0",
      "tax": "0",
      "total": "0",
      "invoicePdfAssetKeySuffix": "teams/65c1e471-205f-4566-9c5a-07198bcdf4ce/billing/2025-2-aUa1nsnCQfxOFnWjqdimZczKKNJJ5xuwlkb-k0XiUOQ=.pdf",
      "monthly": {
        "billingCycle": {
          "year": 2025,
          "month": 2
        },
        "defaultCreditsIssued": {
          "val": "0"
        },
        "autoCreditsIssued": {
          "val": "0"
        },
        "prepaidTokensToSpend": {
          "val": "0"
        },
        "billingItemsCsvAssetKeySuffix": "teams/65c1e471-205f-4566-9c5a-07198bcdf4ce/billing/2025-2-aUa1nsnCQfxOFnWjqdimZczKKNJJ5xuwlkb-k0XiUOQ=-billing_items.csv.zstd",
        "correctionsCsvAssetKeySuffix": "teams/65c1e471-205f-4566-9c5a-07198bcdf4ce/billing/2025-2-aUa1nsnCQfxOFnWjqdimZczKKNJJ5xuwlkb-k0XiUOQ=-corrections.csv.zstd"
      }
    }
  ]
}
```

--------------------------------

### Python (Requests) example: looping year video with keyframes

Source: https://docs.x.ai/developers/model-capabilities/video/reference-to-video

Full example using the xAI API to generate a video with keyframes and a last_frame to create a loop. It posts to /v1/videos/generations, polls the request status, and prints the video URL when done.

```python
import os
import time
import requests

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {os.environ['XAI_API_KEY']}",
}

response = requests.post(
    "https://api.x.ai/v1/videos/generations",
    headers=headers,
    json={
        "model": "grok-imagine-video-1.5",
        "prompt": "A locked-off time-lapse of a single oak and its wheat field across one full year, ending exactly where it began: the young green spring wheat grows tall and ripens to gold under summer skies, a harvest cuts it to stubble and leaves round straw bales as the oak's leaves turn orange and fall, the bales are cleared and snow covers the field and the bare branches, then the snow melts, green shoots return in the rows and the oak leafs out again. Clouds race overhead and the light shifts with the seasons. The camera never moves.",
        "image": {"url": "https://docs.x.ai/assets/api-examples/video/oak-spring.jpg"},
        "keyframes": [
            {"image": {"url": "https://docs.x.ai/assets/api-examples/video/oak-summer.jpg"}, "timestamp_s": 3.0},
            {"image": {"url": "https://docs.x.ai/assets/api-examples/video/oak-autumn.jpg"}, "timestamp_s": 6.0},
            {"image": {"url": "https://docs.x.ai/assets/api-examples/video/oak-winter.jpg"}, "timestamp_s": 9.0},
        ],
        "last_frame": {"url": "https://docs.x.ai/assets/api-examples/video/oak-spring.jpg"},
        "duration": 12,
        "aspect_ratio": "16:9",
        "resolution": "720p",
    },
)

request_id = response.json()["request_id"]

while True:
    result = requests.get(
        f"https://api.x.ai/v1/videos/{request_id}",
        headers={"Authorization": headers["Authorization"]},
    )
    data = result.json()
    if data["status"] == "done":
        print(data["video"]["url"])
        break
    elif data["status"] == "failed":
        print("Video generation failed")
        break
    time.sleep(5)

```

--------------------------------

### Get custom voice audio - Output JSON

Source: https://docs.x.ai/developers/rest-api-reference/inference/voice

Example JSON response for a successful audio download. Shows the HTTP status and the number of audio bytes.

```json
{
  "status": 200,
  "audio_bytes": 1536044
}

```

--------------------------------

### Image and Video Generation - Python (xai_sdk)

Source: https://docs.x.ai/developers/cost-tracking

Example of generating an image and a video using the xai_sdk client and retrieving the cost in USD.

```APIDOC
## Image and Video Generation - Python (xai_sdk)

### Description
Generates an image and a video using the xai_sdk client and retrieves the cost in USD from the response objects.

### Method
POST

### Endpoint
https://api.x.ai/v1/images/generations
https://api.x.ai/v1/videos/generations

### Parameters
#### Request Body
- **model** (string) - Required - The model to use for generation (e.g., "grok-imagine-image-2.0" for image, "grok-imagine-video-1.5" for video).
- **prompt** (string) - Required - The prompt describing the content to generate.

### Request Example
```json
{
  "model": "grok-imagine-image-2.0",
  "prompt": "A cat on a rocket"
}
```

### Response
#### Success Response (200)
- **cost_usd** (number) - The cost of the generation in USD.

#### Response Example
```json
{
  "cost_usd": 0.04
}
```

```

--------------------------------

### List batches - GET /v1/batches

Source: https://docs.x.ai/developers/rest-api-reference/inference/batches

Lists all batches for the current team. The example shows no parameters, and the response contains an array of batch objects with state information.

```json
No parameters.
```

```json
{
  "batches": [
    {
      "batch_id": "batch_1934e8b5-f3dc-45f1-8329-9841b0aee9d8",
      "name": "My New Batch",
      "create_time": "2025-11-11",
      "expire_time": "2025-11-12",
      "create_api_key_id": "********-****-****-****-************",
      "cancel_time": null,
      "cancel_by_xai_message": null,
      "state": {
        "num_requests": 0,
        "num_pending": 0,
        "num_success": 0,
        "num_error": 0,
        "num_cancelled": 0
      }
    },
    {
      "batch_id": "batch_bac0e657-6bbf-46ba-a671-1d73a67c132a",
      "name": "MyNewBatch",
      "create_time": "2025-11-09",
      "expire_time": "2025-11-10",
      "create_api_key_id": "********-****-****-****-************",
      "cancel_time": "2025-11-09",
      "cancel_by_xai_message": null,
      "state": {
        "num_requests": 1,
        "num_pending": 0,
        "num_success": 1,
        "num_error": 0,
        "num_cancelled": 0
      }
    }
  ]
}
```

--------------------------------

### Python (OpenAI SDK): Use file_search and code_interpreter tools

Source: https://docs.x.ai/developers/tools/collections-search

Uses the OpenAI Python SDK with xAI's base URL. Requires a pre-created collection and document uploads. The example sends a question about Tesla production and enables code execution for calculations. Replace 'your_collection_id_here' with the actual collection ID.

```python
import os
from openai import OpenAI

# Using OpenAI SDK with xAI API (requires pre-created collection)
api_key = os.getenv("XAI_API_KEY")
client = OpenAI(
    api_key=api_key,
    base_url="https://api.x.ai/v1",
)

# Note: You must create the collection and upload documents first using either the xAI console (console.x.ai) or the xAI SDK
# The collection_id below should be replaced with your actual collection ID
response = client.responses.create(
    model="grok-4.7",
    input=[
        {
            "role": "user",
            "content": "How many consumer vehicles did Tesla produce in total in 2024 and 2025? Show your working and cite your sources.",
        },
    ],
    tools=[
        {
            "type": "file_search",
            "vector_store_ids": ["your_collection_id_here"],  # Replace with actual collection ID
            "max_num_results": 10
        },
        {"type": "code_interpreter"},  # Enable code execution for calculations
    ],
)

print(response)
```

--------------------------------

### Structured Outputs: Get the desired data

Source: https://docs.x.ai/developers/release-notes

Example of the structured output returned by Grok when using the specified schema. The response contains the requested fields with their values.

```json
{
  "title": "Star Wars",
  "rating": 8.6
}
```

--------------------------------

### Set up ADC and project with gcloud

Source: https://docs.x.ai/developers/community/google-cloud-vertex-ai

Authenticate and set the GCP project for Application Default Credentials (ADC). Replace YOUR_PROJECT_ID with your actual project ID.

```bash
gcloud auth application-default login
gcloud config set project YOUR_PROJECT_ID

```

--------------------------------

### GET /v1/videos/{request_id} - Bash example

Source: https://docs.x.ai/developers/rest-api-reference/inference/videos

Bash curl command to retrieve the result of a deferred video generation request. Uses environment variables VIDEO_REQUEST_ID and XAI_API_KEY.

```Bash
curl -s "https://api.x.ai/v1/videos/$VIDEO_REQUEST_ID" \
  -H "Authorization: Bearer $XAI_API_KEY"
```

--------------------------------

### Connect to MCP Server with TypeScript SDK

Source: https://docs.x.ai/developers/docs-mcp

Example using the MCP TypeScript SDK to connect to the server, list doc pages, and get a specific page. Requires the @modelcontextprotocol/sdk package.

```javascript
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';

const client = new Client({ name: 'my-app', version: '1.0.0' });

const transport = new StreamableHTTPClientTransport(
  new URL('https://docs.x.ai/api/mcp'),
);

await client.connect(transport);

// List all available doc pages
const result = await client.callTool({ name: 'list_doc_pages' });

console.log(result);

// Get a specific page
const page = await client.callTool({
  name: 'get_doc_page',
  arguments: { slug: 'developers/quickstart' },
});

console.log(page);
```

--------------------------------

### Generate video with reference audio using xai_sdk

Source: https://docs.x.ai/developers/model-capabilities/video/reference-to-video

Uses the xai_sdk client to generate a video with reference_audios and reference_images. Requires XAI_API_KEY environment variable. The prompt uses <AUDIO_0> and <AUDIO_1> tags to reference the voices.

```Python
import os
import xai_sdk

client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))

response = client.video.generate(
    prompt="The person from <IMAGE_0> presents the product from <IMAGE_1> on the set from <IMAGE_2>, speaking with the voice from <AUDIO_0>. A second speaker with the voice from <AUDIO_1> replies.",
    model="grok-imagine-video-1.5",
    reference_image_urls=[
        "<IMAGE_URL_1>",
        "<IMAGE_URL_2>",
        "<IMAGE_URL_3>",
    ],
    reference_audios=[
        {"voice_id": "eve"},
        {"voice_id": "leo"},
    ],
    duration=8,
    aspect_ratio="9:16",
    resolution="720p",
)

print(response.url)

```

--------------------------------

### Define CollatzResult schema in Python (Pydantic)

Source: https://docs.x.ai/developers/model-capabilities/text/structured-outputs

Defines a Pydantic model for structured output of Collatz sequence steps, with fields for starting number and steps. Used with client-side tools example.

```python
from pydantic import BaseModel, Field

class CollatzResult(BaseModel):
    starting_number: int = Field(description="The input number")
    steps: int = Field(description="Number of steps to reach 1")

```
Tokens:
Raw