AI Image Generation API
Generate social media images from text prompts using 4 AI models. Images are automatically saved to your media library and can be attached to posts via the Posts API.
Endpoints
/ai/generate-imageOverview
The AI Image Generation API lets you create images from text prompts and immediately use them in social media posts. Choose from four models optimized for different use cases — from fast drafts to photorealistic quality. Every generated image is automatically saved to your media library and returned with a media_id you can pass directly to the Posts API.
4 AI Models
From 1-credit fast drafts to 15-credit photorealistic quality. Pick the right model for your use case.
7 Aspect Ratios
Generate images sized for any platform — Instagram feed, Stories, YouTube thumbnails pins, and more.
Instant Posting
Generated images are saved to your media library automatically. Use the media_id in posts immediately.
/ai/generate-imageGenerate an image from a text prompt. The image is created synchronously and saved to your media library. Requires the ai scope on your API key.
Authentication: Bearer token with ai scope. See Authentication.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
prompt | string | Yes | Text description of the image to generate. Be specific — include style, lighting, composition, and subject details for best results. |
model | string | Yes | AI model to use: nano-banana-pro, ideogram-v2, gemini-3-pro, or flux-schnell |
aspect_ratio | string | No | Image aspect ratio. Default: 1:1. Options: 1:1, 16:9, 9:16, 4:3, 3:4, 4:5, 5:4 |
Example request
curl -X POST https://app.posteverywhere.ai/api/v1/ai/generate-image \
-H "Authorization: Bearer pe_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A flat-lay photo of a coffee cup, notebook, and succulent on a marble desk, warm morning light, minimal aesthetic",
"model": "gemini-3-pro",
"aspect_ratio": "1:1"
}'Response fields
| Field | Type | Description |
|---|---|---|
media_id | string | Unique identifier for the generated image. Use this in POST /posts to attach the image to a post. |
model | string | The model used for generation |
credits_used | integer | Number of AI credits consumed by this generation |
credits_remaining | integer | AI credits remaining on your account after this generation |
status | string | completed on success, failed on error |
image_url | string | CDN URL of the generated image (WebP format via Cloudflare CDN) |
{
"data": {
"media_id": "med_a1b2c3d4e5f6",
"model": "gemini-3-pro",
"credits_used": 5,
"credits_remaining": 45,
"status": "completed",
"image_url": "https://cdn.posteverywhere.ai/media/med_a1b2c3d4e5f6/original.webp"
},
"meta": {
"request_id": "req_abc123",
"timestamp": "2026-03-02T10:00:00Z"
}
}Error responses
| Status | Meaning | Description |
|---|---|---|
400 | Bad Request | Invalid model, invalid aspect ratio, empty prompt, or prompt blocked by safety filter |
401 | Unauthorized | Missing or invalid API key |
402 | Payment Required | Insufficient AI credits. Response includes credits_remaining and credits_required |
403 | Forbidden | API key missing the ai scope. Regenerate your key with the ai scope enabled. |
429 | Too Many Requests | AI rate limit exceeded (50 requests per 5 minutes or 200 per hour). Check Retry-After header. |
500 | Server Error | Image generation failed. Retry with exponential backoff. |
{
"error": {
"code": "insufficient_credits",
"message": "You need 5 AI credits for this generation but only have 2 remaining.",
"credits_remaining": 2,
"credits_required": 5
},
"meta": {
"request_id": "req_xyz789",
"timestamp": "2026-03-02T10:05:00Z"
}
}Available models
Choose the model that best fits your use case. Higher-credit models produce higher quality results, while lower-credit models are ideal for rapid iteration and testing.
| Model | model value | Credits | Best For | Max Resolution |
|---|---|---|---|---|
| Nano Banana Pro | nano-banana-pro | 15 | Highest quality, photorealistic | 2048 x 2048 |
| Ideogram v2 | ideogram-v2 | 8 | Text-in-image (logos, quotes, typography) | 1024 x 1024 |
| Gemini 3 Pro | gemini-3-pro | 5 | Balance of speed and quality | 1536 x 1536 |
| Flux Schnell | flux-schnell | 1 | Fast and cheap, quick iterations | 1024 x 1024 |
All models are available on every PostEverywhere plan. Credit costs are deducted from your monthly AI credit allowance. See the Models page for in-depth comparisons and sample outputs.
Aspect ratios
Choose an aspect ratio optimized for your target platform. If no aspect_ratio is provided, the default is 1:1.
| Ratio | Best For |
|---|---|
1:1 | Instagram feed, Facebook, LinkedIn |
16:9 | YouTube thumbnails, X/Twitter headers |
9:16 | Instagram Stories, TikTok, YouTube Shorts |
4:3 | Facebook feed, presentations |
3:4 | Portrait posts |
4:5 | Instagram portrait posts |
5:4 | Landscape social posts |
Using generated images in posts
The complete workflow: generate an image, then use its media_id to create a post. No upload step is needed — the generated image is already in your media library.
Generate the image
Call POST /ai/generate-image with your prompt. Save the returned media_id.
curl -X POST https://app.posteverywhere.ai/api/v1/ai/generate-image \
-H "Authorization: Bearer pe_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A flat-lay photo of a coffee cup, notebook, and succulent on a marble desk, warm morning light, minimal aesthetic",
"model": "gemini-3-pro",
"aspect_ratio": "1:1"
}'
# Response: { "data": { "media_id": "med_a1b2c3d4e5f6", ... } }Create a post with the image
Pass the media_id from step 1 into the media_ids array when creating a post via the Posts API.
curl -X POST https://app.posteverywhere.ai/api/v1/posts \
-H "Authorization: Bearer pe_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" \
-H "Content-Type: application/json" \
-d '{
"content": "Morning vibes at the home office. What does your workspace look like?",
"account_ids": [1, 2, 3],
"media_ids": ["med_a1b2c3d4e5f6"],
"scheduled_at": "2026-03-15T14:00:00Z"
}'AI credits & billing
AI image generation uses credits that are included in your PostEverywhere plan. Each model has a different credit cost — check credits_remaining in every response to monitor your balance.
| Plan | Monthly AI Credits | Example Usage |
|---|---|---|
| Starter ($19/mo) | 50 credits | 10 Gemini 3 Pro images or 50 Flux Schnell images |
| Growth ($39/mo) | 500 credits | 100 Gemini 3 Pro images or 500 Flux Schnell images |
| Pro ($79/mo) | 2,000 credits | 400 Gemini 3 Pro images or 2,000 Flux Schnell images |
Running low on credits?
When you receive a 402 error, your credits are insufficient for the requested model. You can purchase additional credit packs from your billing dashboard, or upgrade to a higher plan for more monthly credits.
Rate limits
AI image generation has dedicated rate limits separate from the general API. These limits apply per API key.
| Window | Limit |
|---|---|
| Per 5 minutes | 50 requests |
| Per hour | 200 requests |
Rate limit headers
Every response includes rate limit headers so you can track your usage and avoid hitting limits.
| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum requests allowed in the current window |
X-RateLimit-Remaining | Requests remaining in the current window |
X-RateLimit-Reset | Unix timestamp when the rate limit window resets |
Retry-After | Seconds to wait before retrying (only on 429 responses) |
For more details, see the Rate Limits & Errors reference.
Code examples
Generate an AI image in your language of choice. All examples use the gemini-3-pro model with a 1:1 aspect ratio.
cURL
curl -X POST https://app.posteverywhere.ai/api/v1/ai/generate-image \
-H "Authorization: Bearer pe_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A flat-lay photo of a coffee cup, notebook, and succulent on a marble desk, warm morning light, minimal aesthetic",
"model": "gemini-3-pro",
"aspect_ratio": "1:1"
}'Python
import requests
response = requests.post(
"https://app.posteverywhere.ai/api/v1/ai/generate-image",
headers={"Authorization": "Bearer pe_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"},
json={
"prompt": "A flat-lay photo of a coffee cup, notebook, and succulent on a marble desk",
"model": "gemini-3-pro",
"aspect_ratio": "1:1"
}
)
image = response.json()["data"]
print(f"Image ready: {image['image_url']} (used {image['credits_used']} credits)")Node.js
const response = await fetch('https://app.posteverywhere.ai/api/v1/ai/generate-image', {
method: 'POST',
headers: {
'Authorization': 'Bearer pe_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4',
'Content-Type': 'application/json'
},
body: JSON.stringify({
prompt: 'A flat-lay photo of a coffee cup, notebook, and succulent on a marble desk',
model: 'gemini-3-pro',
aspect_ratio: '1:1'
})
});
const { data } = await response.json();
console.log(`Image ready: ${data.image_url} (used ${data.credits_used} credits)`);Full workflow — Generate image & create post (Python)
import requests
API_KEY = "pe_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
BASE_URL = "https://app.posteverywhere.ai/api/v1"
headers = {"Authorization": f"Bearer {API_KEY}"}
# Step 1: Generate an AI image
image_response = requests.post(
f"{BASE_URL}/ai/generate-image",
headers=headers,
json={
"prompt": "A flat-lay photo of a coffee cup, notebook, and succulent on a marble desk, warm morning light, minimal aesthetic",
"model": "gemini-3-pro",
"aspect_ratio": "1:1"
}
)
image_data = image_response.json()["data"]
media_id = image_data["media_id"]
print(f"Generated image: {image_data['image_url']}")
print(f"Credits used: {image_data['credits_used']}, remaining: {image_data['credits_remaining']}")
# Step 2: Create a post with the generated image
post_response = requests.post(
f"{BASE_URL}/posts",
headers=headers,
json={
"content": "Morning vibes at the home office. What does your workspace look like?",
"account_ids": [1, 2, 3],
"media_ids": [media_id],
"scheduled_at": "2026-03-15T14:00:00Z"
}
)
post_data = post_response.json()["data"]
print(f"Post scheduled: {post_data['id']}")Full workflow — Generate image & create post (Node.js)
const API_KEY = 'pe_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4';
const BASE_URL = 'https://app.posteverywhere.ai/api/v1';
const headers = {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json'
};
// Step 1: Generate an AI image
const imageRes = await fetch(`${BASE_URL}/ai/generate-image`, {
method: 'POST',
headers,
body: JSON.stringify({
prompt: 'A flat-lay photo of a coffee cup, notebook, and succulent on a marble desk, warm morning light, minimal aesthetic',
model: 'gemini-3-pro',
aspect_ratio: '1:1'
})
});
const { data: image } = await imageRes.json();
console.log(`Generated image: ${image.image_url}`);
console.log(`Credits used: ${image.credits_used}, remaining: ${image.credits_remaining}`);
// Step 2: Create a post with the generated image
const postRes = await fetch(`${BASE_URL}/posts`, {
method: 'POST',
headers,
body: JSON.stringify({
content: 'Morning vibes at the home office. What does your workspace look like?',
account_ids: [1, 2, 3],
media_ids: [image.media_id],
scheduled_at: '2026-03-15T14:00:00Z'
})
});
const { data: post } = await postRes.json();
console.log(`Post scheduled: ${post.id}`);Frequently asked questions
How much does AI image generation cost?
Can I use generated images in posts immediately?
What happens when I run out of AI credits?
Which AI model should I choose?
Are there content restrictions on AI image generation?
What image format is generated?
Related documentation
Start generating AI images
Get your API key and generate your first AI image in under 2 minutes.