Grok Image Format (Image)¶
Official Documentation
📝 Introduction¶
The Grok image generation interface is compatible with the OpenAI-style REST API, generating images based on text prompts via POST /v1/images/generations. When forwarded through the agtcloud gateway, please use https://api-cs-al.naci-tech.com as the base URL and include your API Key.
| Model | Description |
|---|---|
| grok-imagine-image-pro | Advanced image model, suitable for high-quality, detailed scenes |
| grok-imagine-image | General image generation model |
💡 Request Examples¶
Create Image ✅¶
# Basic image generation (returns URL)
curl https://api-cs-al.naci-tech.com/v1/images/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
"model": "grok-imagine-image-pro",
"prompt": "A cat in a tree",
"n": 1,
"response_format": "url"
}'
# Generate multiple images
curl https://api-cs-al.naci-tech.com/v1/images/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
"model": "grok-imagine-image",
"prompt": "A cat in a tree",
"n": 2,
"response_format": "url"
}'
# Use base64 return format
curl https://api-cs-al.naci-tech.com/v1/images/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
"model": "grok-imagine-image-pro",
"prompt": "A cat in a tree",
"response_format": "b64_json"
}'
# Specify aspect ratio (optional)
curl https://api-cs-al.naci-tech.com/v1/images/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
"model": "grok-imagine-image",
"prompt": "Mountain landscape at sunrise",
"aspect_ratio": "16:9"
}'
# Specify resolution (optional: 1k / 2k)
curl https://api-cs-al.naci-tech.com/v1/images/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $API_KEY" \
-d '{
"model": "grok-imagine-image",
"prompt": "Mountain landscape at sunrise",
"resolution": "2k"
}'
Response Example (response_format: url):
Response Example (response_format: b64_json):
Python Call Example (OpenAI-style REST):
"""
Grok Image Generation API Example (OpenAI-style REST)
- Endpoint: POST /v1/images/generations
"""
import requests
API_BASE = "https://api-cs-al.naci-tech.com"
API_KEY = ""
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def generate_image(
prompt: str,
n: int = 1,
response_format: str = "url",
):
"""
Generate images using Grok models in OpenAI style.
"""
body = {
"prompt": prompt,
"model": "grok-imagine-image-pro", # Options: grok-imagine-image-pro, grok-imagine-image
"response_format": response_format,
"n": n,
}
resp = requests.post(
f"{API_BASE}/v1/images/generations",
headers=HEADERS,
json=body,
timeout=30,
)
if not resp.ok:
try:
err = resp.json()
except Exception:
err = resp.text
print(f"[{resp.status_code}] {err}")
resp.raise_for_status()
return resp.json()
if __name__ == "__main__":
# Example: Generate 2 image URLs
res = generate_image(
prompt="A cat in a tree",
n=2,
response_format="url", # For base64, use "b64_json"
)
print("Response:", res)
📮 Request¶
Endpoint¶
Endpoint: Create Image¶
Creates an image based on a text prompt. Compatible with xAI Image Generation. Base URL is https://api-cs-al.naci-tech.com when using agtcloud gateway.
Authentication¶
Include the following in the request header for API Key authentication:
Where $API_KEY is your API Key from agtcloud.
Request Body Parameters¶
Parameters: Create Image¶
prompt¶
- Type: String
- Required: Yes
- Description: Text description of the desired image.
model¶
- Type: String
- Required: Yes
- Description: Model used for image generation.
grok-imagine-image-pro: Advanced image modelgrok-imagine-image: General image model
n¶
- Type: Integer
- Required: No
- Default: 1
- Description: Number of images to generate. Must be between 1 and 10.
response_format¶
- Type: String
- Required: No
- Default: url
- Description: Format of the returned images.
url: Returns temporary image URLs (recommended to download or process promptly)b64_json: Returns base64 encoded image data
aspect_ratio¶
- Type: String
- Required: No
- Description: Aspect ratio of the generated images. If not provided, the model chooses automatically. Example values:
| Aspect Ratio | Use Case |
|---|---|
1:1 |
Social media, thumbnails |
16:9 / 9:16 |
Widescreen, vertical, stories |
4:3 / 3:4 |
Presentations, portraits |
3:2 / 2:3 |
Photography |
2:1 / 1:2 |
Banners, headers |
19.5:9 / 9:19.5 |
Common phone screens |
20:9 / 9:20 |
Ultra-wide |
auto |
Automatically chosen by the model based on the prompt |
resolution¶
- Type: String
- Required: No
- Description: Output resolution of the generated images. Currently supported:
| Resolution | Description |
|---|---|
1k |
1k resolution |
2k |
2k resolution |
Reference: xAI Image Generation - Resolution
user¶
- Type: String
- Required: No
- Description: Unique identifier representing the end-user for monitoring and risk control.
📥 Response¶
Successful Response¶
created¶
- Type: Integer
- Description: Timestamp when the response was created.
data¶
- Type: Array
- Description: List of generated image objects.
Image Object¶
url¶
- Type: String
- Description: Temporary URL for the generated image when
response_formatisurl. Please download or use promptly as links have an expiration time.
b64_json¶
- Type: String
- Description: Base64 encoded image data when
response_formatisb64_json.
🌟 Notes and Limitations¶
- Max images per request: 10 images.
- URL Validity: Returned URLs are temporary; please download or process in a timely manner.
- Content Moderation: Image generation is subject to content policies and may be filtered for violations.
- Output Format: Images are typically in JPG format.
For more information (such as image editing, style transfer, etc.), please refer to xAI Image Generation.