Grok Imagine Image Text-to-Image API by xAI
xai/grok-imagine-image/text-to-image
Text-to-image
xAI Grok Imagine generates images from natural-language prompts at 1K or 2K resolution, with 14 aspect ratios.
xAI Grok Imagine generates images from natural-language prompts at 1K or 2K resolution, with 14 aspect ratios.
import requests
import time
# Step 1: Start image generation
generate_url = "https://api.atlascloud.ai/api/v1/model/generateImage"
headers = {
"Content-Type": "application/json",
"Authorization": "Bearer $ATLASCLOUD_API_KEY"
}
data = {
"model": "xai/grok-imagine-image/text-to-image", # Required. Model name
"prompt": "A collage of London landmarks in a stenciled street-art style.", # Required. Natural-language description of the image to generate
"num_images": 1, # Number of images to generate. options: 1 | 2 | 3 | 4
"aspect_ratio": "1:1", # Aspect ratio of the generated image
"resolution": "1k", # Output resolution. options: 1k | 2k
"enable_base64_output": False, # If enabled, the output will be encoded into a BASE64 string instead of a URL
}
generate_response = requests.post(generate_url, headers=headers, json=data)
generate_result = generate_response.json()
prediction_id = generate_result["data"]["id"]
# Step 2: Poll for result
poll_url = f"https://api.atlascloud.ai/api/v1/model/prediction/{prediction_id}"
def check_status():
while True:
response = requests.get(poll_url, headers={"Authorization": "Bearer $ATLASCLOUD_API_KEY"})
result = response.json()
if result["data"]["status"] == "completed":
print("Generated image:", result["data"]["outputs"][0])
return result["data"]["outputs"][0]
elif result["data"]["status"] == "failed":
raise Exception(result["data"]["error"] or "Generation failed")
else:
# Still processing, wait 2 seconds
time.sleep(2)
image_url = check_status()安裝所需的相依套件。
pip install requests所有 API 請求都需要透過 API Key 進行認證。您可以在 Atlas Cloud 控制台取得 API Key。
export ATLASCLOUD_API_KEY="your-api-key-here"import os
API_KEY = os.environ.get("ATLASCLOUD_API_KEY")
headers = {
"Content-Type": "application/json",
"Authorization": f"Bearer {API_KEY}"
}切勿在客戶端程式碼或公開儲存庫中暴露您的 API Key。請使用環境變數或後端代理。
import requests
url = "https://api.atlascloud.ai/api/v1/model/generateImage"
headers = {
"Content-Type": "application/json",
"Authorization": "Bearer $ATLASCLOUD_API_KEY"
}
data = {
"model": "your-model",
"prompt": "A beautiful landscape"
}
response = requests.post(url, headers=headers, json=data)
print(response.json())提交一個非同步生成請求。API 會傳回一個 prediction ID，您可以用它來檢查狀態與取得結果。
/api/v1/model/generateImageimport requests
url = "https://api.atlascloud.ai/api/v1/model/generateImage"
headers = {
"Content-Type": "application/json",
"Authorization": "Bearer $ATLASCLOUD_API_KEY"
}
data = {
"model": "xai/grok-imagine-image/text-to-image",
"prompt": "A beautiful landscape with mountains and lake"
}
response = requests.post(url, headers=headers, json=data)
result = response.json()
print(f"Prediction ID: {result['data']['id']}")
print(f"Status: {result['data']['status']}"){
"code": 200,
"data": {
"id": "pred_abc123",
"status": "processing",
"model": "model-name",
"created_at": "2025-01-01T00:00:00Z"
}
}輪詢 prediction 端點以檢查請求的當前狀態。
/api/v1/model/prediction/{prediction_id}import requests
import time
prediction_id = "pred_abc123"
url = f"https://api.atlascloud.ai/api/v1/model/prediction/{prediction_id}"
headers = { "Authorization": "Bearer $ATLASCLOUD_API_KEY" }
while True:
response = requests.get(url, headers=headers)
result = response.json()
status = result["data"]["status"]
print(f"Status: {status}")
if status in ["completed", "succeeded"]:
output_url = result["data"]["outputs"][0]
print(f"Output URL: {output_url}")
break
elif status == "failed":
print(f"Error: {result['data'].get('error', 'Unknown')}")
break
time.sleep(3)processing請求仍在處理中。completed生成完成，輸出可用。succeeded生成成功，輸出可用。failed生成失敗，請檢查 error 欄位。{
"data": {
"id": "pred_abc123",
"status": "completed",
"outputs": [
"https://storage.atlascloud.ai/outputs/result.png"
],
"metrics": {
"predict_time": 8.3
},
"created_at": "2025-01-01T00:00:00Z",
"completed_at": "2025-01-01T00:00:10Z"
}
}將檔案上傳到 Atlas Cloud 儲存空間，取得可在 API 請求中使用的 URL。使用 multipart/form-data 上傳。
/api/v1/model/uploadMediaimport requests
url = "https://api.atlascloud.ai/api/v1/model/uploadMedia"
headers = { "Authorization": "Bearer $ATLASCLOUD_API_KEY" }
with open("image.png", "rb") as f:
files = {"file": ("image.png", f, "image/png")}
response = requests.post(url, headers=headers, files=files)
result = response.json()
download_url = result["data"]["download_url"]
print(f"File URL: {download_url}"){
"data": {
"download_url": "https://storage.atlascloud.ai/uploads/abc123/image.png",
"file_name": "image.png",
"content_type": "image/png",
"size": 1024000
}
}以下參數在請求主體中被接受。
{
"model": "xai/grok-imagine-image/text-to-image",
"prompt": "A collage of London landmarks in a stenciled street-art style.",
"num_images": 1,
"aspect_ratio": "1:1",
"resolution": "1k",
"enable_base64_output": false
}API 傳回包含生成輸出 URL 的 prediction 回應。
{
"id": "pred_abc123",
"status": "completed",
"model": "model-name",
"outputs": [
"https://storage.atlascloud.ai/outputs/result.png"
],
"metrics": {
"predict_time": 8.3
},
"created_at": "2025-01-01T00:00:00Z",
"completed_at": "2025-01-01T00:00:10Z"
}Atlas Cloud Skills 將 400+ AI 模型直接整合到您的 AI 程式碼助手中。一條命令安裝，即可用自然語言生成圖片、影片，以及與 LLM 對話。
npx skills add AtlasCloudAI/atlas-cloud-skills從 Atlas Cloud 控制台取得 API Key，並將其設定為環境變數。
export ATLASCLOUD_API_KEY="your-api-key-here"安裝完成後，您可以在 AI 助手中使用自然語言存取所有 Atlas Cloud 模型。
Atlas Cloud MCP Server 透過 Model Context Protocol 將您的 IDE 與 400+ AI 模型連接。支援任何相容 MCP 的客戶端。
npx -y atlascloud-mcp將以下設定新增到您的 IDE 的 MCP 設定檔中。
{
"mcpServers": {
"atlascloud": {
"command": "npx",
"args": [
"-y",
"atlascloud-mcp"
],
"env": {
"ATLASCLOUD_API_KEY": "your-api-key-here"
}
}
}
}{
"info": {
"title": "AtlasCloud API",
"version": "1.0.0",
"description": "The AtlasCloud API."
},
"paths": {
"/api/v1/model/prediction/{request_id}": {
"get": {
"parameters": [
{
"in": "path",
"name": "request_id",
"required": true,
"schema": {
"description": "Request ID",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PredictionResponse"
}
}
},
"description": "Result of the request."
}
}
},
"x-api-name": "model_result"
},
"/api/v1/model/generateImage": {
"post": {
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Input"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PredictionResponse"
}
}
},
"description": "The request status."
}
}
},
"x-api-name": "model_run"
}
},
"openapi": "3.0.0",
"servers": [
{
"url": "https://api.atlascloud.ai"
}
],
"components": {
"schemas": {
"Input": {
"type": "object",
"required": [
"model",
"prompt"
],
"properties": {
"model": {
"type": "string",
"description": "Model name.",
"default": "xai/grok-imagine-image/text-to-image"
},
"prompt": {
"type": "string",
"default": "A collage of London landmarks in a stenciled street-art style.",
"description": "Natural-language description of the image to generate."
},
"num_images": {
"type": "integer",
"default": 1,
"enum": [
1,
2,
3,
4
],
"description": "Number of images to generate. Each image is billed separately."
},
"aspect_ratio": {
"type": "string",
"default": "1:1",
"enum": [
"1:1",
"3:4",
"4:3",
"9:16",
"16:9",
"2:3",
"3:2",
"9:19.5",
"19.5:9",
"9:20",
"20:9",
"1:2",
"2:1"
],
"description": "Aspect ratio of the generated image."
},
"resolution": {
"type": "string",
"default": "1k",
"enum": [
"1k",
"2k"
],
"description": "Output resolution. 1k = 1024x1024, 2k = 2048x2048."
},
"enable_base64_output": {
"type": "boolean",
"title": "Enable Output base64",
"default": false,
"disabled": true,
"description": "If enabled, the output will be encoded into a BASE64 string instead of a URL."
}
},
"x-order-properties": [
"model",
"prompt",
"num_images",
"aspect_ratio",
"resolution",
"enable_base64_output"
]
},
"PredictionResponse": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the prediction, the ID of the prediction to get."
},
"urls": {
"type": "object",
"description": "Object containing related API endpoints."
},
"model": {
"type": "string",
"description": "Model ID used for the prediction."
},
"status": {
"type": "string",
"description": "Status of the task: created, processing, completed, or failed."
},
"outputs": {
"type": "array",
"items": {
"type": "string"
},
"description": "Array of URLs to the generated images (empty when status is not completed)."
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "ISO timestamp of when the request was created."
}
}
}
},
"securitySchemes": {
"apiKeyAuth": {
"in": "header",
"name": "Authorization",
"type": "apiKey"
}
}
}
}# xai/grok-imagine-image/text-to-image
> xAI Grok Imagine generates images from natural-language prompts at 1K or 2K resolution, with 14 aspect ratios.
## Overview
- **Submit endpoint (POST)**: `https://api.atlascloud.ai/api/v1/model/generateImage` — start an async generation; returns a `prediction_id`
- **Poll endpoint (GET)**: `https://api.atlascloud.ai/api/v1/model/prediction/{prediction_id}` — poll this until the prediction finishes
- **Model ID**: `xai/grok-imagine-image/text-to-image`
## API Information
This model can be used via our HTTP API or more conveniently via our client libraries.
See the input and output schema below, as well as the usage examples.
### Input Schema
The API accepts the following input parameters:
- **`model`** (`string`, _required_):
Model name.
- Default: `"xai/grok-imagine-image/text-to-image"`
- **`prompt`** (`string`, _required_):
Natural-language description of the image to generate.
- Default: `"A collage of London landmarks in a stenciled street-art style."`
- **`num_images`** (`integer`, _optional_):
Number of images to generate. Each image is billed separately.
- Default: `1`
- Options: 1, 2, 3, 4
- **`aspect_ratio`** (`string`, _optional_):
Aspect ratio of the generated image.
- Default: `"1:1"`
- Options: "1:1", "3:4", "4:3", "9:16", "16:9", "2:3", "3:2", "9:19.5", "19.5:9", "9:20", "20:9", "1:2", "2:1"
- **`resolution`** (`string`, _optional_):
Output resolution. 1k = 1024x1024, 2k = 2048x2048.
- Default: `"1k"`
- Options: "1k", "2k"
- **`enable_base64_output`** (`boolean`, _optional_):
If enabled, the output will be encoded into a BASE64 string instead of a URL.
- Default: `false`
**Required Parameters Example**:
```json
{
"model": "xai/grok-imagine-image/text-to-image",
"prompt": "A collage of London landmarks in a stenciled street-art style."
}
```
**Full Example**:
```json
{
"model": "xai/grok-imagine-image/text-to-image",
"prompt": "A collage of London landmarks in a stenciled street-art style.",
"num_images": 1,
"aspect_ratio": "1:1",
"resolution": "1k",
"enable_base64_output": false
}
```
### Output Schema
The API returns the following output format:
- **`id`** (`string`, _optional_):
Unique identifier for the prediction, the ID of the prediction to get.
- **`urls`** (`object`, _optional_):
Object containing related API endpoints.
- **`model`** (`string`, _optional_):
Model ID used for the prediction.
- **`status`** (`string`, _optional_):
Status of the task: created, processing, completed, or failed.
- **`outputs`** (`array[string]`, _optional_):
Array of URLs to the generated images (empty when status is not completed).
- **`created_at`** (`string`, _optional_):
ISO timestamp of when the request was created.
**Example Response**:
```json
{
"id": "",
"urls": {},
"model": "",
"status": "",
"outputs": [
""
],
"created_at": ""
}
```
## Usage Examples
### cURL
```bash
# Step 1: Start generation (async)
curl -X POST "https://api.atlascloud.ai/api/v1/model/generateImage" \
-H "Authorization: Bearer $ATLASCLOUD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "xai/grok-imagine-image/text-to-image",
"prompt": "A collage of London landmarks in a stenciled street-art style.",
"num_images": 1,
"aspect_ratio": "1:1",
"resolution": "1k",
"enable_base64_output": false
}'
# Response will contain: {"code": 200, "data": {"id": "prediction_id", "status": "processing"}}
# Step 2: Poll for result (replace {prediction_id} with the id returned above)
curl -X GET "https://api.atlascloud.ai/api/v1/model/prediction/{prediction_id}" \
-H "Authorization: Bearer $ATLASCLOUD_API_KEY"
# Keep polling until status is "completed", "succeeded" or "failed"
# When completed, outputs will contain the generated content URL(s)
```
## Additional Resources
### Documentation
- [Model Playground](https://www.atlascloud.ai/models/xai/grok-imagine-image/text-to-image)
Ancient futuristic city carved into towering desert cliffs, monumental architecture, vast dunes surrounding the city, warm golden tones, mysterious atmosphere, cinematic sci-fi worldbuilding, ultra detailed, epic scale, volumetric sunlight, Dune aesthetic
Ancient futuristic city carved into towering desert cliffs, monumental architecture, vast dunes surrounding the city, warm golden tones, mysterious atmosphere, cinematic sci-fi worldbuilding, ultra detailed, epic scale, volumetric sunlight, Dune aesthetic