Grok Imagine Image 2 Serverless API
Text-to-image and image editing with crisp, legible text.
POST /v2/grok-imagine-image-2 · submit + poll 1# pip install "segmind>=1.1.0"
2# export SEGMIND_API_KEY="YOUR_API_KEY"
3import segmind
4
5# Async (v2): submit to the queue and block until COMPLETED.
6# run() returns the final result dict (600s deadline, 1.0s poll by default).
7result = segmind.run(
8 "grok-imagine-image-2",
9 prompt="A cozy ramen shop on a narrow Tokyo alley at night in the rain, glowing red and blue neon signs reflecting on the wet pavement, steam rising from a fresh bowl of ramen on a wooden counter, warm lantern light spilling from the doorway, a lone customer seated inside, cinematic street photography, ultra-detailed, sharp focus, shallow depth of field, 35mm",
10 quality="medium",
11 aspect_ratio="16:9",
12 resolution="1k",
13 n=1,
14 output_format="png",
15)
16print(result["status"]) # COMPLETED
17print(result.get("output")) # model output (e.g. media URL)
18print(result["metrics"]["inference_time"]) # server compute seconds
19
20# --- Or submit + poll manually (track request_id, control the cadence) ---
21from segmind import SegmindClient, InferenceFailed, InferenceTimeout
22
23client = SegmindClient() # reads SEGMIND_API_KEY
24payload = {
25 "prompt": "A cozy ramen shop on a narrow Tokyo alley at night in the rain, glowing red and blue neon signs reflecting on the wet pavement, steam rising from a fresh bowl of ramen on a wooden counter, warm lantern light spilling from the doorway, a lone customer seated inside, cinematic street photography, ultra-detailed, sharp focus, shallow depth of field, 35mm",
26 "quality": "medium",
27 "aspect_ratio": "16:9",
28 "resolution": "1k",
29 "n": 1,
30 "output_format": "png",
31}
32job = client.submit_async("grok-imagine-image-2", **payload)
33print(job.request_id) # available immediately
34try:
35 result = job.wait(timeout=600, interval=1.0)
36except InferenceTimeout as e:
37 print("still running:", e.request_id)
38except InferenceFailed as e:
39 print("failed:", e.detail) 1# pip install "segmind>=1.1.0"
2# export SEGMIND_API_KEY="YOUR_API_KEY"
3import segmind
4
5# Async (v2): submit to the queue and block until COMPLETED.
6# run() returns the final result dict (600s deadline, 1.0s poll by default).
7result = segmind.run(
8 "grok-imagine-image-2",
9 prompt="A cozy ramen shop on a narrow Tokyo alley at night in the rain, glowing red and blue neon signs reflecting on the wet pavement, steam rising from a fresh bowl of ramen on a wooden counter, warm lantern light spilling from the doorway, a lone customer seated inside, cinematic street photography, ultra-detailed, sharp focus, shallow depth of field, 35mm",
10 quality="medium",
11 aspect_ratio="16:9",
12 resolution="1k",
13 n=1,
14 output_format="png",
15)
16print(result["status"]) # COMPLETED
17print(result.get("output")) # model output (e.g. media URL)
18print(result["metrics"]["inference_time"]) # server compute seconds
19
20# --- Or submit + poll manually (track request_id, control the cadence) ---
21from segmind import SegmindClient, InferenceFailed, InferenceTimeout
22
23client = SegmindClient() # reads SEGMIND_API_KEY
24payload = {
25 "prompt": "A cozy ramen shop on a narrow Tokyo alley at night in the rain, glowing red and blue neon signs reflecting on the wet pavement, steam rising from a fresh bowl of ramen on a wooden counter, warm lantern light spilling from the doorway, a lone customer seated inside, cinematic street photography, ultra-detailed, sharp focus, shallow depth of field, 35mm",
26 "quality": "medium",
27 "aspect_ratio": "16:9",
28 "resolution": "1k",
29 "n": 1,
30 "output_format": "png",
31}
32job = client.submit_async("grok-imagine-image-2", **payload)
33print(job.request_id) # available immediately
34try:
35 result = job.wait(timeout=600, interval=1.0)
36except InferenceTimeout as e:
37 print("still running:", e.request_id)
38except InferenceFailed as e:
39 print("failed:", e.detail)API Endpoint
https://api.segmind.com/v1/grok-imagine-image-2Parameters
promptrequiredstringText prompt for the image or edit to apply. Write like a design brief with exact quoted text.
"A cozy ramen shop on a narrow Tokyo alley at night in the rain, glowing red and blue neon signs reflecting on the wet pavement, steam rising from a fresh bowl of ramen on a wooden counter, warm lantern light spilling from the doorway, a lone customer seated inside, cinematic street photography, ultra-detailed, sharp focus, shallow depth of field, 35mm"aspect_ratiooptionalstringOutput aspect ratio, ignored when an input image sets size. Use 16:9 landscape, 9:16 social, 1:1 square.
"16:9""1:1""3:4""4:3""9:16""16:9""2:3""3:2""9:19.5""19.5:9""9:20"+4 moreimage_urlsoptionalstring[]Optional source images to edit, up to 3 (extras ignored); switches to editing mode. Omit for text-to-image.
noptionalintegerNumber of images per request, 1 to 4. Use 2-3 to compare variations, 1 when dialed in.
1Range: 1 - 4output_formatoptionalstringOutput file format. Use jpeg for small files, png for lossless, webp for a balance.
"png""jpeg""png""webp"qualityoptionalstringRendering effort: low is faster, medium maximizes fidelity and in-image text. Use medium for final renders.
"medium""low""medium"resolutionoptionalstringOutput resolution, 1k or 2k. Use 1k for fast drafts, 2k for detailed final renders.
"1k""1k""2k"Response Type
Returns: Image
Asynchronous requests (v2)
Use Async for video, long-running (>~60s), or high-concurrency workloads; Sync is simplest for fast image & LLM calls. Async submits a request and you poll it to completion.
- 1
POST /v2/grok-imagine-image-2Submit — returns request_id, status_url, response_url
- 2
GET /v2/requests/{id}/statusPoll — until COMPLETED or FAILED
- 3
GET /v2/requests/{id}Result — final response body
Status states
- A FAILED request is served as HTTP 422 — the body still carries the error detail.
- An unknown or expired request_id returns HTTP 404.
- Results are retained for 1 hour, then expire.
- Content / RAI blocks surface as FAILED, not a separate state.
- Track completion by polling the status endpoint.
Common Error Codes
The API returns standard HTTP status codes. Detailed error messages are provided in the response body.
Bad Request
Invalid parameters or request format
Unauthorized
Missing or invalid API key
Forbidden
Insufficient permissions
Not Found
Model or endpoint not found
Insufficient Credits
Not enough credits to process request
Rate Limited
Too many requests
Server Error
Internal server error
Bad Gateway
Service temporarily unavailable
Timeout
Request timed out