Introduction to XAI (Grok)
Welcome to the XAI service documentation! This service integrates xAI’s Grok models for AI-powered image and video generation. Usinggrok-imagine-image and grok-imagine-video, you can create stunning visual content from text prompts, or use reference images to guide generation.
Features
XAI Grok offers the following generation capabilities:- Text-to-Image: Generate high-quality images from text prompts using the grok-imagine-image model, with customizable aspect ratios.
- Image-to-Image: Provide a reference image along with a prompt to edit or transform images — output dimensions follow the reference image.
- Text-to-Video: Generate videos from text prompts using the grok-imagine-video model, with control over duration (6s / 10s / 15s), aspect ratio, and resolution.
- Image-to-Video: Use a reference image to guide video generation — when provided, aspect ratio and resolution follow the reference image automatically.
- Async Task System: All generation requests return a
taskId. Poll the task endpoint to get status and results.
How to Use XAI
- Create a Generation Task: Call the image or video generation endpoint with your prompt and parameters.
- Get Task ID: The response returns a
taskIdfor tracking. - Poll Task Status: Use the task result endpoint (
GET /xai/tasks) to check progress. - Download Results: Once the task status is
completed, the result contains your generated content.
Available Endpoints
Image Generation
| Endpoint | Method | Description |
|---|---|---|
/xai/images | POST | Generate images from text prompts or reference images |
Video Generation
| Endpoint | Method | Description |
|---|---|---|
/xai/videos | POST | Generate videos from text prompts or reference images |
Task Management
| Endpoint | Method | Description |
|---|---|---|
/xai/tasks | GET | Query task status and results by taskId |
Explore the API Documentation
Image:- Generate Image — Create or edit images with Grok
- Generate Video — Create videos from text or images
- Get Task Result — Check task status and download results
Key Parameters
Image Generation
| Parameter | Required | Description |
|---|---|---|
prompt | Yes | Image description (max 1000 characters) |
model | Yes | grok-imagine-image |
aspectRatio | No | 1:1, 2:3, 3:2, 9:16, 16:9 |
images | No | Reference image URL (max 1); when provided, output size follows the reference |
Video Generation
| Parameter | Required | Description |
|---|---|---|
prompt | Yes | Video description (max 1000 characters) |
model | Yes | grok-imagine-video |
duration | No | 6 (default), 10, or 15 seconds |
aspectRatio | No | 1:1, 2:3, 3:2, 9:16, 16:9 |
resolution | No | 480P, 720P (default) |
images | No | Reference image URL (max 1); when provided, aspectRatio and resolution are ignored |
Task Status Values
| Status | Description |
|---|---|
pending | Task is queued |
ready | Task is ready to be processed |
assigned | Task has been assigned to a worker |
processing | Task is currently being processed |
completed | Task finished successfully |
failed | Task encountered an error |
cancelled | Task was cancelled |
timeout | Task timed out |
Best Practices
- Write Clear Prompts: Be specific and descriptive to get more accurate results.
- Use Reference Images: When available, provide a reference image for more precise control over style and composition.
- Choose Appropriate Settings: Select the right aspect ratio, duration, and resolution for your use case.
- Implement Polling: Use exponential backoff when polling task status to avoid rate limiting.
- Handle Errors Gracefully: Check for
failedandtimeoutstatuses, and useerrorMessage/errorCodefor diagnostics.