POST Image Generation API
/api/v1/ai/image-generation
Generate marketing visuals and product creatives from text prompts.
Architecture Role & AI Definition
Image Generation API provides low-latency, deterministic REST execution for production engineering workflows. It processes structured payloads with strict schema validation, returns uniform JSON envelopes, and is secured via SHA-256 API key authentication with atomic credit pre-authorization locks.
Production Reliability Guidelines
Configure a hard client timeout of 5 to 8 seconds. If network latency spikes, cancel connection to avoid holding open sockets in worker pools.
Upon receiving 429 Rate Limit or transient 5xx, pause with exponential backoff:
wait = min(max_backoff, base * 2^attempt + jitter).
RSFlowHub acquires an atomic lock verifying base credits before model invocation. If validation fails, zero credits are deducted.
Request Body Parameters
| Field | Type | Required | Description |
|---|---|---|---|
prompt |
string | Required | Image generation prompt (Max: 4,000 chars) |
style |
string | Optional | Visual style, e.g. "photorealistic", "illustration", "3d_render" |
aspect_ratio |
string | Optional | Image shape: "1:1", "3:2", "2:3", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9" or "21:9". Default is "1:1". |
size |
string | Optional | Older way to pick the shape, e.g. "1024x1024" or "1024x1792": mapped to the closest aspect ratio. Images are always about 1 megapixel. Ignored when aspect_ratio is set. |
n |
integer | Optional | Number of images to generate (1 to 4). Each generated image is billed separately. |
150 credits per generated image, plus 1 credit per image for every 1,000 prompt characters. You only pay for images that are actually returned: ask for n: 4 and get 3, you pay for 3. A prompt blocked by the safety filter returns 422 CONTENT_BLOCKED and costs nothing.
Image generation needs a paid plan (free-plan credits alone return 403 PLAN_UPGRADE_REQUIRED) and is limited to 30 images per account per day (429 DAILY_LIMIT_REACHED, resets at midnight).
Each image is a JPEG (check mime_type) of about 1 megapixel (1024x1024 for 1:1). Its URL stays available for 7 days (expires_at); save the files you want to keep. Generation takes a few seconds, so use an HTTP timeout of at least 60 seconds.
Example Request
{
"prompt": "Clean product hero image for a developer API dashboard",
"style": "photorealistic",
"aspect_ratio": "16:9",
"n": 2
}curl -X POST https://rsflowhub.com/api/v1/ai/image-generation \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Clean product hero image for a developer API dashboard",
"style": "photorealistic",
"aspect_ratio": "16:9",
"n": 2
}'Example Response
{
"success": true,
"request_id": "req_7f3a9c2d1e4b8a6f",
"data": {
"result": {
"images": [
{
"url": "https://rsflowhub.com/storage/generated/20260927/img_3f9c1a7e5b2d4c8f9e0a6b1d2c3e4f5a6b7c8d9e.jpg",
"mime_type": "image/jpeg",
"width": 1344,
"height": 768,
"expires_at": "2026-10-04T12:34:56+00:00"
},
{
"url": "https://rsflowhub.com/storage/generated/20260927/img_8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b.jpg",
"mime_type": "image/jpeg",
"width": 1344,
"height": 768,
"expires_at": "2026-10-04T12:34:56+00:00"
}
]
}
},
"meta": {
"version": "v1",
"timestamp": "2026-09-27T12:34:56+00:00"
}
}API Request Example
Use the cURL snippet below to test the endpoint.
curl -X POST 'https://rsflowhub.com/api/v1/ai/image-generation' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"prompt": "Clean product hero image for a developer API dashboard",
"style": "photorealistic",
"aspect_ratio": "16:9",
"n": 2
}'Want to try it without code? Test this request in the live Playground.
Common Failure Modes & Troubleshooting Matrix
| HTTP Code | Error Code | Root Cause | Recommended Remediation |
|---|---|---|---|
| 401 | API_KEY_MISSING / INVALID_API_KEY |
No key sent, or the key was mistyped or regenerated. | Copy the current key from Dashboard → API Keys and send it as Authorization: Bearer (or X-API-Key). |
| 402 | INSUFFICIENT_CREDITS |
Your balance cannot cover the estimate for this call (base 120 credits plus input/output size). | Buy a plan in Dashboard → Billing. Nothing was charged. |
| 422 | VALIDATION_ERROR |
A field is missing, too long or the wrong type, or the body is not valid JSON. | Read error.details for the field messages and fix the request. Do not retry the same body. |
| 429 | RATE_LIMIT_EXCEEDED |
Your plan-wide or per-endpoint per-minute limit was reached. | Wait the seconds in the Retry-After header, then retry with jitter. Rate limits |
| 502 | AI_PROVIDER_ERROR |
The AI model and its backup both failed. | Retry with backoff and check the status page. Nothing was charged. |