Ideogram v4 API, Ideogram RMBG API, Ideogram 2.0, Turbo API: Pricing, Documentation
by Ideogram
Ideogram v4 API, developers can create images containing logos, signs, typography, and text elements that render correctly. The API offers both standard and turbo variants, plus features like image editing, remixing, and description generation.

Models Version
Get $5 Free Credit on First Payment
No strings attached — add funds and get $5 bonus instantly
Ideogram v4 API Documentation
https://gateway.pixazo.ai/ideogram-v4/v1/ideogram-v4-request
Authentication
All requests require an API key passed via header.
| Header | Type | Required | Description |
|---|---|---|---|
| Ocp-Apim-Subscription-Key | string | Yes | Your API subscription key |
Ideogram V4 generate request
Request Code
POST https://gateway.pixazo.ai/ideogram-v4/v1/ideogram-v4-request
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_API_KEY
{
"prompt": "A vintage travel poster of Kyoto in autumn, bold hand-painted lettering reading KYOTO across the top",
"num_images": 1,
"image_size": "square_hd",
"output_format": "jpeg",
"rendering_speed": "BALANCED",
"acceleration": "none",
"enable_prompt_expansion": true,
"enable_safety_checker": true,
"sync_mode": false
}
import requests
url = "https://gateway.pixazo.ai/ideogram-v4/v1/ideogram-v4-request"
headers = {
"Content-Type": "application/json",
"Cache-Control": "no-cache",
"Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
}
data = {
"prompt": "A vintage travel poster of Kyoto in autumn, bold hand-painted lettering reading KYOTO across the top",
"num_images": 1,
"image_size": "square_hd",
"output_format": "jpeg",
"rendering_speed": "BALANCED",
"acceleration": "none",
"enable_prompt_expansion": true,
"enable_safety_checker": true,
"sync_mode": false
}
response = requests.post(url, json=data, headers=headers)
print(response.json())
const url = "https://gateway.pixazo.ai/ideogram-v4/v1/ideogram-v4-request";
const headers = {
"Content-Type": "application/json",
"Cache-Control": "no-cache",
"Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
};
const data = {
"prompt": "A vintage travel poster of Kyoto in autumn, bold hand-painted lettering reading KYOTO across the top",
"num_images": 1,
"image_size": "square_hd",
"output_format": "jpeg",
"rendering_speed": "BALANCED",
"acceleration": "none",
"enable_prompt_expansion": true,
"enable_safety_checker": true,
"sync_mode": false
};
fetch(url, {
method: "POST",
headers: headers,
body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));
curl -X POST "https://gateway.pixazo.ai/ideogram-v4/v1/ideogram-v4-request" \
-H "Content-Type: application/json" \
-H "Cache-Control: no-cache" \
-H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
--data-raw '{
"prompt": "A vintage travel poster of Kyoto in autumn, bold hand-painted lettering reading KYOTO across the top",
"num_images": 1,
"image_size": "square_hd",
"output_format": "jpeg",
"rendering_speed": "BALANCED",
"acceleration": "none",
"enable_prompt_expansion": true,
"enable_safety_checker": true,
"sync_mode": false
}'
Output
{
"request_id": "ideogram-v4_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"status": "QUEUED",
"polling_url": "https://gateway.pixazo.ai/v2/requests/status/ideogram-v4_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
Webhook (Optional)
Add the X-Webhook-URL header to your generate request to receive a POST callback instead of polling.
X-Webhook-URL: https://your-server.com/webhook/callback
Request Parameters - Ideogram V4 generate request
| Parameter | Required | Type | Default | Allowed values / range | Description |
|---|---|---|---|---|---|
| prompt | Yes | string | — | — | Text prompt for image generation. Must describe the desired visual content with clarity. |
| num_images | No | integer | 1 | 1, 2, 3, 4 | Number of images to generate. |
| image_size | No | string or object | "square_hd" | "square_hd", "square", "portrait_4_3", "portrait_16_9", "landscape_4_3", "landscape_16_9", or custom {width, height} object | Image dimensions preset or custom resolution. |
| output_format | No | string | "jpeg" | "jpeg", "png" | Output image format. |
| rendering_speed | No | string | "BALANCED" | "TURBO", "BALANCED", "QUALITY" | Quality vs speed trade-off tier. |
| acceleration | No | string | "none" | "none", "low", "regular", "high" | Hardware acceleration level. Higher values may reduce generation time but increase cost. |
| expansion_model | No | string | "Medium" | "None", "Medium", "Large" | Which model expands (rewrites and enriches) your prompt before generation. "None" disables prompt expansion and skips its fee; "Medium" is fast; "Large" uses Ideogram's Magic Prompt for the highest quality. |
| enable_safety_checker | No | boolean | true | — | Turns on automatic filtering of unsafe or explicit (NSFW) content. Leave enabled unless you have a specific reason to disable it. |
| seed | No | integer | — | — | Random seed that controls the generation's randomness. Reuse the same seed with identical settings to reproduce the same result; leave it empty for a different output each time. |
| sync_mode | No | boolean | false | — | If on, the finished file is sent back directly instead of as a download link. Handy for quick tests; for normal use, leave it off to get a download link. |
Example Request
{
"prompt": "A vintage travel poster of Kyoto in autumn, bold hand-painted lettering reading KYOTO across the top",
"num_images": 1,
"image_size": "square_hd",
"output_format": "jpeg",
"rendering_speed": "BALANCED",
"acceleration": "none",
"enable_prompt_expansion": true,
"enable_safety_checker": true,
"sync_mode": false
}
Response
{
"request_id": "ideogram-v4_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"status": "QUEUED",
"polling_url": "https://gateway.pixazo.ai/v2/requests/status/ideogram-v4_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
Request Headers
| Header | Value |
|---|---|
| Content-Type | application/json |
| Cache-Control | no-cache |
| Ocp-Apim-Subscription-Key | YOUR_API_KEY |
Response Handling
Common status codes.
| Code | Meaning |
|---|---|
| 202 | Accepted — Request queued |
| 400 | Bad Request |
| 401 | Unauthorized |
| 402 | Insufficient Balance |
| 403 | Forbidden |
| 429 | Too Many Requests |
| 500 | Internal Server Error |
Error Responses
Queue system errors and model validation errors.
Queue System Errors
// 402 — Insufficient balance
{
"error": "Insufficient Balance",
"message": "Your wallet does not have enough balance."
}
// 400 — Model not found
{
"error": "Model not found",
"message": "Model 'ideogram-v4' not found or is disabled"
}
Error via Status/Webhook
{
"request_id": "ideogram-v4_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"status": "ERROR",
"model_id": "ideogram-v4",
"error": "Description of the error",
"output": null
}
Retrieving Results
Poll the universal status endpoint to check progress and retrieve results.
Endpoint
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
cURL Example
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
"https://gateway.pixazo.ai/v2/requests/status/ideogram-v4_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
Response (Completed)
{
"request_id": "ideogram-v4_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"status": "COMPLETED",
"model_id": "ideogram-v4",
"error": null,
"output": {
"media_url": ["https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/ideogram-v4_019dxxxx/output.jpeg"],
"media_type": "image/jpeg"
},
"created_at": "2026-03-31T10:00:00.000Z",
"updated_at": "2026-03-31T10:00:15.000Z",
"completed_at": "2026-03-31T10:00:15.000Z"
}
Response Fields
| Field | Type | Description |
|---|---|---|
| request_id | string | Unique request identifier |
| status | string | QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR |
| model_id | string | Model that processed the request |
| error | string|null | Error message if failed |
| output.media_url | array | URLs to generated media (R2 CDN) |
| output.media_type | string | MIME type of the output |
| created_at | string | When request was created |
| completed_at | string | When request completed |
| polling_url | string | Status URL (initial response only) |
Status Values
| Status | Description |
|---|---|
| QUEUED | Request accepted, waiting to be processed |
| PROCESSING | Being processed by the model |
| COMPLETED | Done — output contains the result |
| FAILED | Failed — check error field |
| ERROR | System error — not charged |
Status Flow
QUEUED → PROCESSING → COMPLETED
→ FAILED
→ ERROR
Typical Workflow
- Send a generate request to the API endpoint
- Save the
request_idfrom the response - Poll every 5-10 seconds:
GET /v2/requests/status/{request_id} - When
statusis"COMPLETED", download fromoutput.media_url
Tip: Use X-Webhook-URL header to get a callback instead of polling.
Ideogram v4 API Pricing
Higher tier = more detail and better prompt adherence at higher cost and latency. Use Turbo for speed, Balanced for everyday work, Quality for final assets.
| Resolution | Price (USD) |
|---|---|
| Per megapixel (Turbo) | $0.03 |
| Per megapixel (Balanced) | $0.06 |
| Per megapixel (Quality) | $0.10 |
Ideogram v4 API Documentation
https://gateway.pixazo.ai/ideogram-v4-image-to-image/v1/ideogram-v4-image-to-image-request
Authentication
All requests require an API key passed via header.
| Header | Type | Required | Description |
|---|---|---|---|
| Ocp-Apim-Subscription-Key | string | Yes | Your API subscription key |
Ideogram V4 Image to Image generate request
Request Code
POST https://gateway.pixazo.ai/ideogram-v4-image-to-image/v1/ideogram-v4-image-to-image-request
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_API_KEY
{
"prompt": "Restyle as a vibrant watercolor illustration with bold ink outlines",
"image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/Image.jpeg",
"image_size": "auto",
"strength": 0.8,
"num_images": 1,
"rendering_speed": "BALANCED",
"acceleration": "none",
"output_format": "jpeg",
"expansion_model": "Medium",
"enable_safety_checker": true,
"sync_mode": false
}
import requests
url = "https://gateway.pixazo.ai/ideogram-v4-image-to-image/v1/ideogram-v4-image-to-image-request"
headers = {
"Content-Type": "application/json",
"Cache-Control": "no-cache",
"Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
}
data = {
"prompt": "Restyle as a vibrant watercolor illustration with bold ink outlines",
"image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/Image.jpeg",
"image_size": "auto",
"strength": 0.8,
"num_images": 1,
"rendering_speed": "BALANCED",
"acceleration": "none",
"output_format": "jpeg",
"expansion_model": "Medium",
"enable_safety_checker": true,
"sync_mode": false
}
response = requests.post(url, json=data, headers=headers)
print(response.json())
const url = "https://gateway.pixazo.ai/ideogram-v4-image-to-image/v1/ideogram-v4-image-to-image-request";
const headers = {
"Content-Type": "application/json",
"Cache-Control": "no-cache",
"Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
};
const data = {
"prompt": "Restyle as a vibrant watercolor illustration with bold ink outlines",
"image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/Image.jpeg",
"image_size": "auto",
"strength": 0.8,
"num_images": 1,
"rendering_speed": "BALANCED",
"acceleration": "none",
"output_format": "jpeg",
"expansion_model": "Medium",
"enable_safety_checker": true,
"sync_mode": false
};
fetch(url, {
method: "POST",
headers: headers,
body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));
curl -X POST "https://gateway.pixazo.ai/ideogram-v4-image-to-image/v1/ideogram-v4-image-to-image-request" \
-H "Content-Type: application/json" \
-H "Cache-Control: no-cache" \
-H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
--data-raw '{
"prompt": "Restyle as a vibrant watercolor illustration with bold ink outlines",
"image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/Image.jpeg",
"image_size": "auto",
"strength": 0.8,
"num_images": 1,
"rendering_speed": "BALANCED",
"acceleration": "none",
"output_format": "jpeg",
"expansion_model": "Medium",
"enable_safety_checker": true,
"sync_mode": false
}'
Output
{
"request_id": "ideogram-v4-image-to-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"status": "QUEUED",
"polling_url": "https://gateway.pixazo.ai/v2/requests/status/ideogram-v4-image-to-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
Webhook (Optional)
Add the X-Webhook-URL header to your generate request to receive a POST callback instead of polling.
X-Webhook-URL: https://your-server.com/webhook/callback
Request Parameters - Ideogram V4 Image to Image generate request
| Parameter | Required | Type | Default | Allowed values / range | Description |
|---|---|---|---|---|---|
| prompt | Yes | string | — | — | Text prompt describing the desired output. Must be descriptive for best results. |
| image_url | Yes | string | — | — | Upload your input image. JPG, PNG, WebP, GIF, or AVIF. |
| image_size | No | string or object | "auto" | "auto", "square_hd", "square", "portrait_4_3", "portrait_16_9", "landscape_4_3", "landscape_16_9" | Preset aspect ratios: `auto`, `square_hd`, `square`, `portrait_4_3`, `portrait_16_9`, `landscape_4_3`, `landscape_16_9`. Alternatively, provide a custom object with `width` and `height` integers. |
| strength | No | float | 0.8 | 0.0–1.0 | How much the result may differ from the input. Higher values allow bigger changes from the source; lower values keep the output closer to the original. |
| num_images | No | integer | 1 | 1–4 | Number of images to generate. Allowed range: 1–4. |
| rendering_speed | No | string | "BALANCED" | "TURBO", "BALANCED", "QUALITY" | Quality vs speed tier. Allowed: `TURBO`, `BALANCED`, `QUALITY`. |
| acceleration | No | string | "none" | "none", "low", "regular", "high" | Hardware acceleration level. Allowed: `none`, `low`, `regular`, `high`. |
| output_format | No | string | "jpeg" | "jpeg", "png" | Output image format. Allowed: `jpeg`, `png`. |
| expansion_model | No | string | "Medium" | "None", "Medium", "Large" | Model used to expand the prompt for richer generation. Allowed: `None`, `Medium`, `Large`. |
| enable_safety_checker | No | boolean | true | — | Turns on automatic filtering of unsafe or explicit (NSFW) content. Leave enabled unless you have a specific reason to disable it. |
| seed | No | integer | — | — | Random seed that controls the generation's randomness. Reuse the same seed with identical settings to reproduce the same result; leave it empty for a different output each time. |
| sync_mode | No | boolean | false | — | If on, the finished file is sent back directly instead of as a download link. Handy for quick tests; for normal use, leave it off to get a download link. |
Content Item Types & Limits
| Type | Max | Format / Size | Description |
|---|---|---|---|
| image | 1 | JPG, PNG, WEBP, GIF, AVIF · < 10 MB | Input image. |
Example Request
{
"prompt": "Restyle as a vibrant watercolor illustration with bold ink outlines",
"image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/nano-banana/nano-banana-a382a80b-f8df-4de1-a0c1-a5dcfd42dae4-1758783383399.jpg",
"image_size": "auto",
"strength": 0.8,
"num_images": 1,
"rendering_speed": "BALANCED",
"acceleration": "none",
"output_format": "jpeg",
"expansion_model": "Medium",
"enable_safety_checker": true,
"sync_mode": false
}
Response
{
"request_id": "ideogram-v4-image-to-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"status": "QUEUED",
"polling_url": "https://gateway.pixazo.ai/v2/requests/status/ideogram-v4-image-to-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
Request Headers
| Header | Value |
|---|---|
| Content-Type | application/json |
| Cache-Control | no-cache |
| Ocp-Apim-Subscription-Key | YOUR_API_KEY |
Response Handling
Common status codes.
| Code | Meaning |
|---|---|
| 202 | Accepted — Request queued |
| 400 | Bad Request |
| 401 | Unauthorized |
| 402 | Insufficient Balance |
| 403 | Forbidden |
| 429 | Too Many Requests |
| 500 | Internal Server Error |
Error Responses
Queue system errors and model validation errors.
Queue System Errors
// 402 — Insufficient balance
{
"error": "Insufficient Balance",
"message": "Your wallet does not have enough balance."
}
// 400 — Model not found
{
"error": "Model not found",
"message": "Model 'ideogram-v4-image-to-image' not found or is disabled"
}
Error via Status/Webhook
{
"request_id": "ideogram-v4-image-to-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"status": "ERROR",
"model_id": "ideogram-v4-image-to-image",
"error": "Description of the error",
"output": null
}
Retrieving Results
Poll the universal status endpoint to check progress and retrieve results.
Endpoint
GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY
cURL Example
curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
"https://gateway.pixazo.ai/v2/requests/status/ideogram-v4-image-to-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
Response (Completed)
{
"request_id": "ideogram-v4-image-to-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"status": "COMPLETED",
"model_id": "ideogram-v4-image-to-image",
"error": null,
"output": {
"media_url": ["https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/ideogram-v4-image-to-image_019dxxxx/output.jpeg"],
"media_type": "image/jpeg"
},
"created_at": "2026-03-31T10:00:00.000Z",
"updated_at": "2026-03-31T10:00:15.000Z",
"completed_at": "2026-03-31T10:00:15.000Z"
}
Response Fields
| Field | Type | Description |
|---|---|---|
| request_id | string | Unique request identifier |
| status | string | QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR |
| model_id | string | Model that processed the request |
| error | string|null | Error message if failed |
| output.media_url | array | URLs to generated media (R2 CDN) |
| output.media_type | string | MIME type of the output |
| created_at | string | When request was created |
| completed_at | string | When request completed |
| polling_url | string | Status URL (initial response only) |
Status Values
| Status | Description |
|---|---|
| QUEUED | Request accepted, waiting to be processed |
| PROCESSING | Being processed by the model |
| COMPLETED | Done — output contains the result |
| FAILED | Failed — check error field |
| ERROR | System error — not charged |
Status Flow
QUEUED → PROCESSING → COMPLETED
→ FAILED
→ ERROR
Typical Workflow
- Send a generate request to the API endpoint
- Save the
request_idfrom the response - Poll every 5-10 seconds:
GET /v2/requests/status/{request_id} - When
statusis"COMPLETED", download fromoutput.media_url
Tip: Use X-Webhook-URL header to get a callback instead of polling.
Ideogram v4 API Pricing
| Resolution | Price (USD) |
|---|---|
| Per megapixel (Turbo) | $0.03 |
| Per megapixel (Balanced) | $0.06 |
| Per megapixel (Quality) | $0.10 |
Ideogram Remove Background API Documentation
https://gateway.pixazo.ai/ideogram-remove-background/v1/ideogram-remove-background-request
Authentication
All requests require an API key passed via header.
| Header | Type | Required | Description |
|---|---|---|---|
| Ocp-Apim-Subscription-Key | string | Yes | Your API subscription key |
Ideogram Remove Background generate request - Ideogram Remove Background
Request Code
POST https://gateway.pixazo.ai/ideogram-remove-background/v1/ideogram-remove-background-request
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY
{
"image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/Image.jpeg"
}
import requests
url = "https://gateway.pixazo.ai/ideogram-remove-background/v1/ideogram-remove-background-request"
headers = {
"Content-Type": "application/json",
"Cache-Control": "no-cache",
"Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
"image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/Image.jpeg"
}
response = requests.post(url, json=data, headers=headers)
print(response.json())
fetch('https://gateway.pixazo.ai/ideogram-remove-background/v1/ideogram-remove-background-request', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Cache-Control': 'no-cache',
'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
},
body: JSON.stringify({
image_url: 'https://pub-582b7213209642b9b995c96c95a30381.r2.dev/Image.jpeg'
})
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
curl -X POST "https://gateway.pixazo.ai/ideogram-remove-background/v1/ideogram-remove-background-request" \
-H "Content-Type: application/json" \
-H "Cache-Control: no-cache" \
-H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
--data-raw '{
"image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/Image.jpeg"
}'
Output
{
"images": [
{
"file_name": "nano-banana-pro-edit-output.png",
"content_type": "image/png",
"url": "[RESPONSE_URL]"
}
],
"description": ""
}
Request Parameters - Ideogram Remove Background generate request
| Parameter | Required | Type | Default | Allowed values / range | Description |
|---|---|---|---|---|---|
| image_url | Yes | string | — | — | Source image URL. Supported formats: JPEG, PNG, WebP. Max file size 10MB. |
| sync_mode | No | boolean | false | true, false | If on, the finished file is sent back directly instead of as a download link. Handy for quick tests; for normal use, leave it off to get a download link. |
Content Item Types & Limits
| Type | Max | Format / Size | Description |
|---|---|---|---|
| image | 1 | JPEG, PNG, WEBP · < 10 MB | Image to remove the background from. |
Minimum Request
{
"image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/upscaler_019ed0c8-bb34-7854-afbc-b2a164758a15b/output.png"
}
Full Request (all options)
{
"image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/Image.jpeg",
"sync_mode": false
}
Response
{
"request_id": "ideogram-remove-background_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"status": "QUEUED",
"polling_url": "https://gateway.pixazo.ai/v2/requests/status/ideogram-remove-background_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
Response Fields - Ideogram Remove Background generate request
| Field | Type | Description |
|---|---|---|
| request_id | string | Unique identifier for the job submission. |
| status | string | Current status of the request (QUEUED, PROCESSING, etc.). |
| polling_url | string | URL to use for checking the job status. |
Request Headers
| Header | Value |
|---|---|
| Content-Type | application/json |
| Cache-Control | no-cache |
| Ocp-Apim-Subscription-Key | Your subscription key |
Response Handling
Common status codes for Ideogram Remove Background generate request.
| Code | Meaning |
|---|---|
| 200 | Success |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 429 | Too Many Requests |
| 500 | Internal Server Error |
Error Responses
400: Bad Request
{
"error": "Invalid image_url",
"message": "The provided image_url is malformed or unreachable."
}
401: Unauthorized
{
"error": "Unauthorized",
"message": "Missing or invalid Ocp-Apim-Subscription-Key header."
}
Status Workflow
Check status of your request using the polling_url returned in the response.
Status Values
| Status | Description |
|---|---|
| QUEUED | Request accepted, waiting to be processed |
| PROCESSING | Being processed by the model |
| COMPLETED | Done — output contains the result |
| FAILED | Failed — check error field |
| ERROR | System error — not charged |
Status Flow
Submitted
↓
QUEUED
↓
PROCESSING
↓
COMPLETED or FAILED or ERROR
Typical Workflow
- Submit request to /ideogram-remove-background-request
- Receive response with request_id and polling_url
- Make GET requests to polling_url every 2–3 seconds
- When status is COMPLETED, extract output from the response
- Handle FAILED or ERROR states as appropriate
Ideogram Remove Background check status - Ideogram Remove Background
Request Code
POST https://gateway.pixazo.ai/v2/requests/status/ideogram-remove-background_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY
import requests
url = "https://gateway.pixazo.ai/v2/requests/status/ideogram-remove-background_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
headers = {
"Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
response = requests.get(url, headers=headers)
print(response.json())
fetch('https://gateway.pixazo.ai/v2/requests/status/ideogram-remove-background_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', {
method: 'GET',
headers: {
'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
}
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
curl -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
"https://gateway.pixazo.ai/v2/requests/status/ideogram-remove-background_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
Output
{
"images": [
{
"file_name": "nano-banana-pro-edit-output.png",
"content_type": "image/png",
"url": "[RESPONSE_URL]"
}
],
"description": ""
}
Request Parameters - Ideogram Remove Background check status
| Parameter | Required | Type | Default | Allowed values / range | Description |
|---|---|---|---|---|---|
| request_id | Yes | string | — | — | The unique request ID returned from the initial submission endpoint. |
Minimum Request
{
"request_id": "ideogram-remove-background_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
Full Request (all options)
{
"request_id": "ideogram-remove-background_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
Response
{
"request_id": "ideogram-remove-background_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"status": "COMPLETED",
"model_id": "ideogram-remove-background",
"error": null,
"output": {
"media_url": ["https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/ideogram-remove-background_019dxxxx/output.png"],
"media_type": "image/png"
},
"created_at": "2026-03-31T10:00:00.000Z",
"updated_at": "2026-03-31T10:00:15.000Z",
"completed_at": "2026-03-31T10:00:15.000Z"
}
Response Fields - Ideogram Remove Background check status
| Field | Type | Description |
|---|---|---|
| request_id | string | Unique identifier for the request. |
| status | string | Current status of the job (QUEUED, PROCESSING, COMPLETED, FAILED, ERROR). |
| model_id | string | The model used for processing. |
| error | null|string | null if successful, error details if failed. |
| output | object | Contains media_url and media_type for the generated result. |
| output.media_url | array | Array of URLs pointing to the generated media. |
| output.media_type | string | MIME type of the output (e.g., image/png). |
| created_at | string | Timestamp when the request was received. |
| updated_at | string | Timestamp when the request status was last updated. |
| completed_at | string | Timestamp when the request was completed. |
Request Headers
| Header | Value |
|---|---|
| Ocp-Apim-Subscription-Key | Your subscription key |
Response Handling
Common status codes for Ideogram Remove Background check status.
| Code | Meaning |
|---|---|
| 200 | Success |
| 400 | Bad Request - Invalid request_id |
| 401 | Unauthorized |
| 404 | Not Found - Request ID not found |
| 429 | Too Many Requests |
| 500 | Internal Server Error |
Notes & Tips
- Pricing is $0.01 per request.
- Use
sync_mode: trueif you need the output as a data URI directly in the submission response (not recommended for production). - Wait 2–3 seconds between polling requests for optimal performance.
- Implement exponential backoff for retrying failed or system error responses.
- Image must be under 10MB and in JPEG, PNG, or WebP format.
- The output is always a transparent PNG, suitable for compositing.
- Responses from the polling endpoint are not cached — each poll counts toward your usage limits.
- Use the polling URL returned in the initial response — do not construct it manually.
Ideogram Remove Background API Pricing
Ideogram v2 API Documentation
https://gateway.pixazo.ai/ideogramV_2/v1/generate
Create Image - Ideogram Generate API
Request Code
POST https://gateway.pixazo.ai/ideogramV_2/v1/generate
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY
{
"image_request": {
"prompt": "A serene tropical beach scene. Dominating the foreground are tall palm trees with lush green leaves, standing tall against a backdrop of a sandy beach. The beach leads to the azure waters of the sea, which gently kisses the shoreline. In the distance, there is an island or landmass with a silhouette of what appears to be a lighthouse or tower. The sky above is painted with fluffy white clouds, some of which are tinged with hues of pink and orange, suggesting either a sunrise or sunset.",
"negative_prompt": "blur",
"model": "V_2",
"aspect_ratio": "ASPECT_10_16",
"magic_prompt_option": "AUTO",
"seed": 212,
"style_type": "AUTO",
"color_palette": {
"name": "JUNGLE"
}
}
}
import requests
import json
url = "https://gateway.pixazo.ai/ideogramV_2/v1/generate"
headers = {
"Content-Type": "application/json",
"Cache-Control": "no-cache",
"Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
"image_request": {
"prompt": "A serene tropical beach scene. Dominating the foreground are tall palm trees with lush green leaves, standing tall against a backdrop of a sandy beach. The beach leads to the azure waters of the sea, which gently kisses the shoreline. In the distance, there is an island or landmass with a silhouette of what appears to be a lighthouse or tower. The sky above is painted with fluffy white clouds, some of which are tinged with hues of pink and orange, suggesting either a sunrise or sunset.",
"negative_prompt": "blur",
"model": "V_2",
"aspect_ratio": "ASPECT_10_16",
"magic_prompt_option": "AUTO",
"seed": 212,
"style_type": "AUTO",
"color_palette": {
"name": "JUNGLE"
}
}
}
response = requests.post(url, headers=headers, json=data)
print(response.json())
const url = 'https://gateway.pixazo.ai/ideogramV_2/v1/generate';
const headers = {
'Content-Type': 'application/json',
'Cache-Control': 'no-cache',
'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
};
const data = {
image_request: {
prompt: 'A serene tropical beach scene. Dominating the foreground are tall palm trees with lush green leaves, standing tall against a backdrop of a sandy beach. The beach leads to the azure waters of the sea, which gently kisses the shoreline. In the distance, there is an island or landmass with a silhouette of what appears to be a lighthouse or tower. The sky above is painted with fluffy white clouds, some of which are tinged with hues of pink and orange, suggesting either a sunrise or sunset.',
negative_prompt: 'blur',
model: 'V_2',
aspect_ratio: 'ASPECT_10_16',
magic_prompt_option: 'AUTO',
seed: 212,
style_type: 'AUTO',
color_palette: {
name: 'JUNGLE'
}
}
};
fetch(url, {
method: 'POST',
headers: headers,
body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
curl -v -X POST "https://gateway.pixazo.ai/ideogramV_2/v1/generate" \
-H "Content-Type: application/json" \
-H "Cache-Control: no-cache" \
-H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
--data-raw '{
"image_request": {
"prompt": "A serene tropical beach scene. Dominating the foreground are tall palm trees with lush green leaves, standing tall against a backdrop of a sandy beach. The beach leads to the azure waters of the sea, which gently kisses the shoreline. In the distance, there is an island or landmass with a silhouette of what appears to be a lighthouse or tower. The sky above is painted with fluffy white clouds, some of which are tinged with hues of pink and orange, suggesting either a sunrise or sunset.",
"negative_prompt": "blur",
"model": "V_2",
"aspect_ratio": "ASPECT_10_16",
"magic_prompt_option": "AUTO",
"seed": 212,
"style_type": "AUTO",
"color_palette": {
"name": "JUNGLE"
}
}
}'
Output
{
"created": "2024-11-01T10:06:14.744267+00:00",
"data": [
{
"is_image_safe": true,
"prompt": "A serene tropical beach scene...",
"resolution": "800x1280",
"seed": 212,
"style_type": "REALISTIC",
"url": "https://ideogram.ai/api/images/ephemeral/4p6cIwykSjaWcUUavtwuMw.png?exp=1730541994&sig=ef2b2872a29327783454a41061d1e890361cb6a5c77c358c6190793095428b59"
}
]
}
Request Parameters - Create Image
| Parameter | Required | Type | Default | Allowed values / range | Description |
|---|---|---|---|---|---|
| prompt | Yes | string | — | — | Text describing the scene or image to be generated. |
| negative_prompt | No | string | — | — | Description of elements or features to exclude from the generated image. Supported by V_2. |
| model | Yes | string | — | V_2 | The model version to generate with. This product uses V_2. |
| aspect_ratio | No | enum | ASPECT_1_1 | — | Determines the image resolution. Default: ASPECT_1_1. Other values: ASPECT_10_16, ASPECT_16_10, ASPECT_9_16, ASPECT_16_9, ASPECT_3_2, ASPECT_2_3, ASPECT_4_3, ASPECT_3_4, ASPECT_1_1, ASPECT_1_3, ASPECT_3_1 |
| resolution | No | enum | — | — | Explicit output resolution in the form RESOLUTION_<width>_<height> (e.g. RESOLUTION_1024_1024). Cannot be combined with aspect_ratio; when omitted, aspect_ratio determines the resolution. |
| seed | No | integer | — | 0–2147483647 | Random seed that controls the generation's randomness. Reuse the same seed with identical settings to reproduce the same result; leave it empty for a different output each time. |
| magic_prompt_option | No | enum | AUTO | — | Controls use of MagicPrompt. Default: AUTO. Other values: ON, OFF. |
| style_type | No | enum | AUTO | — | Specifies the style type for the image (applies to V_2 and above). Default: AUTO. Other values: GENERAL, FICTION, REALISTIC, DESIGN, RENDER_3D, ANIME |
| color_palette | No | object | — | — | Defines a color palette, either by preset name or as a custom set of hex-color members. Available presets: EMBER, FRESH, JUNGLE, MAGIC, MELON, MOSAIC, PASTEL, ULTRAMARINE |
| num_images | No | integer | 1 | — | Number of images to generate in a single request. |
Example Request
{
"image_request": {
"prompt": "A serene tropical beach scene. Dominating the foreground are tall palm trees with lush green leaves, standing tall against a backdrop of a sandy beach. The beach leads to the azure waters of the sea, which gently kisses the shoreline. In the distance, there is an island or landmass with a silhouette of what appears to be a lighthouse or tower. The sky above is painted with fluffy white clouds, some of which are tinged with hues of pink and orange, suggesting either a sunrise or sunset.",
"negative_prompt": "blur",
"model": "V_2",
"aspect_ratio": "ASPECT_10_16",
"magic_prompt_option": "AUTO",
"seed": 212,
"style_type": "AUTO",
"color_palette": {
"name": "JUNGLE"
}
}
}
Response
{
"created": "2024-11-01T10:06:14.744267+00:00",
"data": [
{
"is_image_safe": true,
"prompt": "A serene tropical beach scene with tall palm trees, a sandy beach, and azure waters...",
"resolution": "800x1280",
"seed": 212,
"style_type": "REALISTIC",
"url": "https://ideogram.ai/api/images/ephemeral/4p6cIwykSjaWcUUavtwuMw.png?exp=1730541994&sig=ef2b2872a29327783454a41061d1e890361cb6a5c77c358c6190793095428b59"
}
]
}
Request Headers
| Header | Value |
|---|---|
| Content-Type | application/json |
| Cache-Control | no-cache |
| Ocp-Apim-Subscription-Key | YOUR_SUBSCRIPTION_KEY |
Response Handling
Common status codes for Create Image.
| Code | Meaning |
|---|---|
| 200 | Success |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 429 | Too Many Requests |
| 500 | Internal Server Error |
Ideogram v2 API Pricing
Ideogram v2 API Documentation
https://gateway.pixazo.ai/ideogram-generate/v1
Describe Image - Ideogram Generate API
Request Code
POST https://gateway.pixazo.ai/ideogramV_2/v1/describe
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY
Content-Type: multipart/form-data
import requests
url = "https://gateway.pixazo.ai/ideogramV_2/v1/describe"
headers = {
"Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
with open("/path/to/your/image.png", "rb") as image_file:
files = {"image_file": image_file}
response = requests.post(url, headers=headers, files=files)
print(response.json())
const formData = new FormData();
formData.append('image_file', fileInput.files[0]);
fetch('https://gateway.pixazo.ai/ideogramV_2/v1/describe', {
method: 'POST',
headers: {
'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
},
body: formData
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
curl -X POST "https://gateway.pixazo.ai/ideogramV_2/v1/describe" \
-H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
-H "Content-Type: multipart/form-data" \
--form 'image_file=@/path/to/your/image.png'
Output
{
"created": "2024-11-01T10:06:14.744267+00:00",
"data": {
"description": "The image depicts a serene tropical beach..."
}
}
Request Parameters - Describe Image
| Parameter | Required | Type | Default | Allowed values / range | Description |
|---|---|---|---|---|---|
| image_file | Yes | File | — | — | The image to describe (JPG, PNG, WEBP; max 10 MB). |
| describe_model_version | No | enum | V_3 | V_2, V_3, V_4 | The model version used to generate the description. Defaults to V_3. |
Content Item Types & Limits
| Type | Max | Format / Size | Description |
|---|---|---|---|
| image | 1 | JPG, PNG, WEBP · < 10 MB | Image to describe. |
Example Request
--form 'image_file=@/path/to/your/image.png'
Response
{
"created": "2024-11-01T10:06:14.744267+00:00",
"data": {
"description": "The image depicts a serene tropical beach scene with tall palm trees and azure waters."
}
}
Request Headers
| Header | Value |
|---|---|
| Ocp-Apim-Subscription-Key | YOUR_SUBSCRIPTION_KEY |
| Content-Type | multipart/form-data |
Response Handling
Common status codes for Describe Image.
| Code | Meaning |
|---|---|
| 200 | Success |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 429 | Too Many Requests |
| 500 | Internal Server Error |
Ideogram v2 API Pricing
Ideogram v2 API Documentation
https://gateway.pixazo.ai/ideogramV_2/v1/edit
Edit Image - Ideogram Generate API
Request Code
POST https://gateway.pixazo.ai/ideogramV_2/v1/edit
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY
Content-Type: multipart/form-data
import requests
url = "https://gateway.pixazo.ai/ideogramV_2/v1/edit"
headers = {
"Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
files = {
"image_file": open("path/to/your/image.png", "rb"),
"mask": open("path/to/your/mask.png", "rb"),
"prompt": (None, "Enhance brightness and remove text"),
"model": (None, "V_2")
}
response = requests.post(url, headers=headers, files=files)
print(response.json())
const formData = new FormData();
formData.append('image_file', document.getElementById('imageFile').files[0]);
formData.append('mask', document.getElementById('maskFile').files[0]);
formData.append('prompt', 'Enhance brightness and remove text');
formData.append('model', 'V_2');
fetch('https://gateway.pixazo.ai/ideogramV_2/v1/edit', {
method: 'POST',
headers: {
'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
},
body: formData
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
curl -X POST "https://gateway.pixazo.ai/ideogramV_2/v1/edit" \
-H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
-H "Content-Type: multipart/form-data" \
--form 'image_file=@/path/to/your/image.png' \
--form 'mask=@/path/to/your/mask.png' \
--form 'prompt="Enhance brightness and remove text"' \
--form 'model="V_2"'
Output
{
"created": "2024-11-01T10:06:14.744267+00:00",
"data": [
{
"is_image_safe": true,
"prompt": "Enhance brightness and remove text",
"edited_image": "https://ideogram.ai/api/images/ephemeral/iSkGI5XfQ-ObReWhAiw_iA.png?exp=1730547982&sig=dabe41c3e4caa3ef788f32acc842cccfb2816686aab3e1a35d69d9139183fdc7"
}
]
}
Request Parameters - Edit Image
| Parameter | Required | Type | Default | Allowed values / range | Description |
|---|---|---|---|---|---|
| image_file | Yes | File | — | — | The image to edit (JPG, PNG, WEBP; max 10 MB). |
| mask | Yes | File | — | — | A black-and-white mask the same size as the image: white marks the regions to edit and black the regions to keep (max 10 MB). Required. |
| prompt | Yes | string | — | — | Text description of the edit to apply to the masked region. |
| model | Yes | string | — | V_2 | The model version used for editing. This product uses V_2. |
| magic_prompt_option | No | enum | — | AUTO, ON, OFF | Controls whether MagicPrompt is used to expand the prompt. |
| seed | No | integer | — | 0–2147483647 | Random seed for reproducible results; omit for a different output each time. |
| style_type | No | enum | — | AUTO, GENERAL, FICTION, REALISTIC, DESIGN, RENDER_3D, ANIME | The visual style to generate with (applies to V_2 and above). |
| num_images | No | integer | 1 | — | Number of edited images to generate in a single request. |
Content Item Types & Limits
| Type | Max | Format / Size | Description |
|---|---|---|---|
| image | 1 | JPG, PNG, WEBP · < 10 MB | Image and mask to edit. |
Example Request
POST https://gateway.pixazo.ai/ideogramV_2/v1/edit
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY
Content-Type: multipart/form-data
--boundary
Content-Disposition: form-data; name="image_file"; filename="image.png"
Content-Type: image/png
[File content]
--boundary
Content-Disposition: form-data; name="mask"; filename="mask.png"
Content-Type: image/png
[File content]
--boundary
Content-Disposition: form-data; name="prompt"
Content-Type: text/plain
Enhance brightness and remove text
--boundary
Content-Disposition: form-data; name="model"
Content-Type: text/plain
V_2
--boundary--
Response
{
"created": "2024-11-01T10:06:14.744267+00:00",
"data": [
{
"is_image_safe": true,
"prompt": "Enhance brightness and remove text",
"original_image": "url_to_original_image",
"edited_image": "https://ideogram.ai/api/images/ephemeral/iSkGI5XfQ-ObReWhAiw_iA.png?exp=1730547982&sig=dabe41c3e4caa3ef788f32acc842cccfb2816686aab3e1a35d69d9139183fdc7",
"model_used": "V_2"
}
]
}
Request Headers
| Header | Value |
|---|---|
| Ocp-Apim-Subscription-Key | YOUR_SUBSCRIPTION_KEY |
| Content-Type | multipart/form-data |
Response Handling
Common status codes for Edit Image.
| Code | Meaning |
|---|---|
| 200 | Success |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 429 | Too Many Requests |
| 500 | Internal Server Error |
Ideogram v2 API Pricing
Ideogram v2 API Documentation
https://gateway.pixazo.ai/ideogramV_2/v1/remix
Remix Image - Ideogram Generate API
Request Code
POST https://gateway.pixazo.ai/ideogramV_2/v1/remix
Ocp-Apim-Subscription-Key: YOUR_Subscription_KEY
Content-Type: multipart/form-data
--boundary
Content-Disposition: form-data; name="image_request"
{"prompt":"A serene tropical beach scene. Dominating the foreground are tall palm trees with lush green leaves, standing tall against a backdrop of a sandy beach. The beach leads to the azure waters of the sea, which gently kisses the shoreline. In the distance, there is an island or landmass with a silhouette of what appears to be a lighthouse or tower. The sky above is painted with fluffy white clouds, some of which are tinged with hues of pink and orange, suggesting either a sunrise or sunset.","aspect_ratio":"ASPECT_10_16","image_weight":50,"magic_prompt_option":"ON","model":"V_2"}
--boundary
Content-Disposition: form-data; name="image_file"; filename="image.png"
Content-Type: image/png
[Binary image data]
--boundary--
import requests
url = "https://gateway.pixazo.ai/ideogramV_2/v1/remix"
headers = {
"Ocp-Apim-Subscription-Key": "YOUR_Subscription_KEY"
}
files = {
"image_request": (None, '{"prompt":"A serene tropical beach scene. Dominating the foreground are tall palm trees with lush green leaves, standing tall against a backdrop of a sandy beach. The beach leads to the azure waters of the sea, which gently kisses the shoreline. In the distance, there is an island or landmass with a silhouette of what appears to be a lighthouse or tower. The sky above is painted with fluffy white clouds, some of which are tinged with hues of pink and orange, suggesting either a sunrise or sunset.","aspect_ratio":"ASPECT_10_16","image_weight":50,"magic_prompt_option":"ON","model":"V_2"}'),
"image_file": ("image.png", open("/path/to/your/image.png", "rb"), "image/png")
}
response = requests.post(url, headers=headers, files=files)
print(response.json())
const formData = new FormData();
formData.append('image_request', '{"prompt":"A serene tropical beach scene. Dominating the foreground are tall palm trees with lush green leaves, standing tall against a backdrop of a sandy beach. The beach leads to the azure waters of the sea, which gently kisses the shoreline. In the distance, there is an island or landmass with a silhouette of what appears to be a lighthouse or tower. The sky above is painted with fluffy white clouds, some of which are tinged with hues of pink and orange, suggesting either a sunrise or sunset.","aspect_ratio":"ASPECT_10_16","image_weight":50,"magic_prompt_option":"ON","model":"V_2"}');
formData.append('image_file', document.getElementById('imageInput').files[0]);
fetch('https://gateway.pixazo.ai/ideogramV_2/v1/remix', {
method: 'POST',
headers: {
'Ocp-Apim-Subscription-Key': 'YOUR_Subscription_KEY'
},
body: formData
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
curl -X POST "https://gateway.pixazo.ai/ideogramV_2/v1/remix" \
-H "Ocp-Apim-Subscription-Key: YOUR_Subscription_KEY" \
-H "Content-Type: multipart/form-data" \
--form 'image_request={
"prompt": "A serene tropical beach scene. Dominating the foreground are tall palm trees with lush green leaves, standing tall against a backdrop of a sandy beach. The beach leads to the azure waters of the sea, which gently kisses the shoreline. In the distance, there is an island or landmass with a silhouette of what appears to be a lighthouse or tower. The sky above is painted with fluffy white clouds, some of which are tinged with hues of pink and orange, suggesting either a sunrise or sunset.",
"aspect_ratio": "ASPECT_10_16",
"image_weight": 50,
"magic_prompt_option": "ON",
"model": "V_2"
}' \
--form 'image_file=@/path/to/your/image.png'
Output
{
"created": "2024-11-01T10:06:14.744267+00:00",
"data": [
{
"is_image_safe": true,
"prompt": "A serene tropical beach scene...",
"resolution": "800x1280",
"image_url": "https://ideogram.ai/api/images/ephemeral/iSkGI5XfQ-ObReWhAiw_iA.png?exp=1730547982&sig=dabe41c3e4caa3ef788f32acc842cccfb2816686aab3e1a35d69d9139183fdc7"
}
]
}
Request Parameters - Remix Image
| Parameter | Required | Type | Default | Allowed values / range | Description |
|---|---|---|---|---|---|
| image_file | Yes | File | — | — | The image to remix (JPG, PNG, WEBP; max 10 MB). |
| image_request | Yes | JSON | — | — | A JSON object, sent as a multipart form field, holding the generation settings listed below (prompt, image_weight, aspect_ratio, etc.). |
| prompt | Yes | string | — | — | Text prompt describing the image to generate from the remix. Sent inside image_request. |
| image_weight | No | integer | 50 | 0–100 | How strongly the input image influences the result (higher = closer to the input image, lower = closer to the prompt). Sent inside image_request. |
| aspect_ratio | No | enum | ASPECT_1_1 | ASPECT_10_16, ASPECT_16_10, ASPECT_9_16, ASPECT_16_9, ASPECT_3_2, ASPECT_2_3, ASPECT_4_3, ASPECT_3_4, ASPECT_1_1, ASPECT_1_3, ASPECT_3_1 | Determines the output resolution. Sent inside image_request. |
| model | No | string | V_2 | V_2 | The model version used for the remix. This product uses V_2. Sent inside image_request. |
| magic_prompt_option | No | enum | — | AUTO, ON, OFF | Controls whether MagicPrompt is used to expand the prompt. Sent inside image_request. |
| seed | No | integer | — | 0–2147483647 | Random seed for reproducible results. Sent inside image_request. |
| style_type | No | enum | — | AUTO, GENERAL, FICTION, REALISTIC, DESIGN, RENDER_3D, ANIME | The visual style to generate with (applies to V_2 and above). Sent inside image_request. |
| negative_prompt | No | string | — | — | Description of elements or features to exclude from the image. Sent inside image_request. |
| num_images | No | integer | 1 | — | Number of images to generate. Sent inside image_request. |
| color_palette | No | object | — | — | Color palette by preset name or custom hex-color members. Presets: EMBER, FRESH, JUNGLE, MAGIC, MELON, MOSAIC, PASTEL, ULTRAMARINE. Sent inside image_request. |
Content Item Types & Limits
| Type | Max | Format / Size | Description |
|---|---|---|---|
| image | 1 | JPG, PNG, WEBP · < 10 MB | Image to remix. |
Example Request
{
"image_request": "{\n \"prompt\": \"A serene tropical beach scene. Dominating the foreground are tall palm trees with lush green leaves, standing tall against a backdrop of a sandy beach. The beach leads to the azure waters of the sea, which gently kisses the shoreline. In the distance, there is an island or landmass with a silhouette of what appears to be a lighthouse or tower. The sky above is painted with fluffy white clouds, some of which are tinged with hues of pink and orange, suggesting either a sunrise or sunset.\",\n \"aspect_ratio\": \"ASPECT_10_16\",\n \"image_weight\": 50,\n \"magic_prompt_option\": \"ON\",\n \"model\": \"V_2\"\n}",
"image_file": "[binary data]"
}
Response
{
"created": "2024-11-01T10:06:14.744267+00:00",
"data": [
{
"is_image_safe": true,
"prompt": "A serene tropical beach scene. Dominating the foreground are tall palm trees with lush green leaves, standing tall against a backdrop of a sandy beach. The beach leads to the azure waters of the sea, which gently kisses the shoreline. In the distance, there is an island or landmass with a silhouette of what appears to be a lighthouse or tower. The sky above is painted with fluffy white clouds, some of which are tinged with hues of pink and orange, suggesting either a sunrise or sunset.",
"resolution": "800x1280",
"image_weight": 50,
"image_url": "https://ideogram.ai/api/images/ephemeral/iSkGI5XfQ-ObReWhAiw_iA.png?exp=1730547982&sig=dabe41c3e4caa3ef788f32acc842cccfb2816686aab3e1a35d69d9139183fdc7",
"model_used": "V_2"
}
]
}
Request Headers
| Header | Value |
|---|---|
| Ocp-Apim-Subscription-Key | YOUR_Subscription_KEY |
| Content-Type | multipart/form-data |
Response Handling
Common status codes for Remix Image.
| Code | Meaning |
|---|---|
| 200 | Success |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 429 | Too Many Requests |
| 500 | Internal Server Error |
Ideogram v2 API Pricing
Ideogram Turbo API Documentation
https://gateway.pixazo.ai/ideogramV_2_Turbo/v1/generate
Create Image - IDEOGRAM IMAGE TURBO API
Request Code
POST https://gateway.pixazo.ai/ideogramV_2_Turbo/v1/generate
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY
{
"image_request": {
"prompt": "A serene tropical beach scene. Dominating the foreground are tall palm trees with lush green leaves, standing tall against a backdrop of a sandy beach. The beach leads to the azure waters of the sea, which gently kisses the shoreline. In the distance, there is an island or landmass with a silhouette of what appears to be a lighthouse or tower. The sky above is painted with fluffy white clouds, some of which are tinged with hues of pink and orange, suggesting either a sunrise or sunset.",
"negative_prompt": "blur",
"model": "V_2_TURBO",
"aspect_ratio": "ASPECT_10_16",
"magic_prompt_option": "AUTO",
"seed": 212,
"style_type": "AUTO",
"color_palette": {
"name": "JUNGLE"
}
}
}
import requests
url = "https://gateway.pixazo.ai/ideogramV_2_Turbo/v1/generate"
headers = {
"Content-Type": "application/json",
"Cache-Control": "no-cache",
"Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
"image_request": {
"prompt": "A serene tropical beach scene. Dominating the foreground are tall palm trees with lush green leaves, standing tall against a backdrop of a sandy beach. The beach leads to the azure waters of the sea, which gently kisses the shoreline. In the distance, there is an island or landmass with a silhouette of what appears to be a lighthouse or tower. The sky above is painted with fluffy white clouds, some of which are tinged with hues of pink and orange, suggesting either a sunrise or sunset.",
"negative_prompt": "blur",
"model": "V_2_TURBO",
"aspect_ratio": "ASPECT_10_16",
"magic_prompt_option": "AUTO",
"seed": 212,
"style_type": "AUTO",
"color_palette": {
"name": "JUNGLE"
}
}
}
response = requests.post(url, json=data, headers=headers)
print(response.json())
const url = 'https://gateway.pixazo.ai/ideogramV_2_Turbo/v1/generate';
const headers = {
'Content-Type': 'application/json',
'Cache-Control': 'no-cache',
'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
};
const data = {
image_request: {
prompt: 'A serene tropical beach scene. Dominating the foreground are tall palm trees with lush green leaves, standing tall against a backdrop of a sandy beach. The beach leads to the azure waters of the sea, which gently kisses the shoreline. In the distance, there is an island or landmass with a silhouette of what appears to be a lighthouse or tower. The sky above is painted with fluffy white clouds, some of which are tinged with hues of pink and orange, suggesting either a sunrise or sunset.',
negative_prompt: 'blur',
model: 'V_2_TURBO',
aspect_ratio: 'ASPECT_10_16',
magic_prompt_option: 'AUTO',
seed: 212,
style_type: 'AUTO',
color_palette: {
name: 'JUNGLE'
}
}
};
fetch(url, {
method: 'POST',
headers: headers,
body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
curl -v -X POST "https://gateway.pixazo.ai/ideogramV_2_Turbo/v1/generate" \
-H "Content-Type: application/json" \
-H "Cache-Control: no-cache" \
-H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
--data-raw '{
"image_request": {
"prompt": "A serene tropical beach scene. Dominating the foreground are tall palm trees with lush green leaves, standing tall against a backdrop of a sandy beach. The beach leads to the azure waters of the sea, which gently kisses the shoreline. In the distance, there is an island or landmass with a silhouette of what appears to be a lighthouse or tower. The sky above is painted with fluffy white clouds, some of which are tinged with hues of pink and orange, suggesting either a sunrise or sunset.",
"negative_prompt": "blur",
"model": "V_2_TURBO",
"aspect_ratio": "ASPECT_10_16",
"magic_prompt_option": "AUTO",
"seed": 212,
"style_type": "AUTO",
"color_palette": {
"name": "JUNGLE"
}
}
}'
Output
{
"created": "2024-11-01T10:06:14.744267+00:00",
"data": [
{
"is_image_safe": true,
"prompt": "A serene tropical beach scene...",
"resolution": "800x1280",
"url": "https://ideogram.ai/api/images/ephemeral/4p6cIwykSjaWcUUavtwuMw.png?exp=1730541994&sig=ef2b2872a29327783454a41061d1e890361cb6a5c77c358c6190793095428b59"
}
]
}
Request Parameters - Create Image
| Parameter | Required | Type | Default | Allowed values / range | Description |
|---|---|---|---|---|---|
| prompt | Yes | string | — | — | Text describing the scene or image to generate. |
| negative_prompt | No | string | — | — | Description of what to exclude from the image. Descriptions in the prompt take precedence over the negative prompt. |
| model | Yes | string | V_2_TURBO | V_2_TURBO | Model version used for generation. This Turbo endpoint uses V_2_TURBO. |
| aspect_ratio | No | enum | ASPECT_1_1 | ASPECT_1_1, ASPECT_10_16, ASPECT_16_10, ASPECT_9_16, ASPECT_16_9, ASPECT_3_2, ASPECT_2_3, ASPECT_4_3, ASPECT_3_4, ASPECT_1_3, ASPECT_3_1 | Determines the image resolution. Cannot be combined with resolution. |
| seed | No | integer | — | 0–2147483647 | Random seed that controls the generation. Reuse the same seed with identical settings to reproduce a result; omit it for a different output each time. |
| magic_prompt_option | No | enum | AUTO | AUTO, ON, OFF | Controls whether MagicPrompt automatically enhances the prompt. |
| style_type | No | enum | AUTO | AUTO, GENERAL, FICTION, REALISTIC, DESIGN, RENDER_3D, ANIME | Style of the generated image. Applies to V_2 and above. |
| color_palette | No | object | — | Preset name or custom members | Color guidance. Use a preset name (EMBER, FRESH, JUNGLE, MAGIC, MELON, MOSAIC, PASTEL, ULTRAMARINE) or a members array of hex colors with optional weights. |
| num_images | No | integer | 1 | 1–8 | Number of images to generate. |
| resolution | No | enum | — | RESOLUTION_* (e.g. RESOLUTION_1024_1024) | Explicit output resolution for V_2-family models. Overrides aspect_ratio and cannot be combined with it. |
Example Request
{
"image_request": {
"prompt": "A serene tropical beach scene. Dominating the foreground are tall palm trees with lush green leaves, standing tall against a backdrop of a sandy beach. The beach leads to the azure waters of the sea, which gently kisses the shoreline. In the distance, there is an island or landmass with a silhouette of what appears to be a lighthouse or tower. The sky above is painted with fluffy white clouds, some of which are tinged with hues of pink and orange, suggesting either a sunrise or sunset.",
"negative_prompt": "blur",
"model": "V_2_TURBO",
"aspect_ratio": "ASPECT_10_16",
"magic_prompt_option": "AUTO",
"seed": 212,
"style_type": "AUTO",
"color_palette": {
"name": "JUNGLE"
}
}
}
Response
{
"created": "2024-11-01T10:06:14.744267+00:00",
"data": [
{
"is_image_safe": true,
"prompt": "A serene tropical beach scene with tall palm trees, a sandy beach, and azure waters...",
"resolution": "800x1280",
"seed": 212,
"style_type": "REALISTIC",
"url": "https://ideogram.ai/api/images/ephemeral/4p6cIwykSjaWcUUavtwuMw.png?exp=1730541994&sig=ef2b2872a29327783454a41061d1e890361cb6a5c77c358c6190793095428b59"
}
]
}
Request Headers
| Header | Value |
|---|---|
| Content-Type | application/json |
| Cache-Control | no-cache |
| Ocp-Apim-Subscription-Key | YOUR_SUBSCRIPTION_KEY |
Response Handling
Common status codes for Create Image.
| Code | Meaning |
|---|---|
| 200 | Success |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 429 | Too Many Requests |
| 500 | Internal Server Error |
Ideogram Turbo API Pricing
Ideogram Turbo API Documentation
https://gateway.pixazo.ai/ideogramV_2_Turbo/v1/describe
Describe Image - Ideogram Image Turbo API
Request Code
POST https://gateway.pixazo.ai/ideogramV_2_Turbo/v1/describe
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY
Content-Type: multipart/form-data
import requests
url = "https://gateway.pixazo.ai/ideogramV_2_Turbo/v1/describe"
headers = {
"Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
with open("/path/to/your/image.png", "rb") as image_file:
files = {"image_file": image_file}
response = requests.post(url, headers=headers, files=files)
print(response.json())
const formData = new FormData();
formData.append('image_file', fileInput.files[0]);
fetch('https://gateway.pixazo.ai/ideogramV_2_Turbo/v1/describe', {
method: 'POST',
headers: {
'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
},
body: formData
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
curl -X POST "https://gateway.pixazo.ai/ideogramV_2_Turbo/v1/describe" \
-H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
-H "Content-Type: multipart/form-data" \
--form 'image_file=@/path/to/your/image.png'
Output
{
"created": "2024-11-01T10:06:14.744267+00:00",
"data": {
"description": "The image depicts a serene tropical beach scene..."
}
}
Request Parameters - Describe Image
| Parameter | Required | Type | Default | Allowed values / range | Description |
|---|---|---|---|---|---|
| image_file | Yes | File | — | JPEG, PNG, WebP (max 10 MB) | The image to describe. Only JPEG, PNG, and WebP are supported; maximum size 10 MB. |
| describe_model_version | No | enum | V_3 | V_2, V_3, V_4 | Model version used to describe the image. |
Content Item Types & Limits
| Type | Max | Format / Size | Description |
|---|---|---|---|
| image | 1 | JPG, PNG, WEBP · < 10 MB | Image to describe. |
Example Request
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="image_file"; filename="image.png"
Content-Type: image/png
<binary image data>
------WebKitFormBoundary7MA4YWxkTrZu0gW--
Response
{
"created": "2024-11-01T10:06:14.744267+00:00",
"data": {
"description": "The image depicts a serene tropical beach scene with tall palm trees and azure waters."
}
}
Request Headers
| Header | Value |
|---|---|
| Ocp-Apim-Subscription-Key | YOUR_SUBSCRIPTION_KEY |
| Content-Type | multipart/form-data |
Response Handling
Common status codes for Describe Image.
| Code | Meaning |
|---|---|
| 200 | Success |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 429 | Too Many Requests |
| 500 | Internal Server Error |
Ideogram Turbo API Pricing
Ideogram Turbo API Documentation
https://gateway.pixazo.ai/ideogramV_2_Turbo/v1/edit
Edit Image - Ideogram Image Turbo API
Request Code
POST https://gateway.pixazo.ai/ideogramV_2_Turbo/v1/edit
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY
Content-Type: multipart/form-data
[form data]
import requests
url = "https://gateway.pixazo.ai/ideogramV_2_Turbo/v1/edit"
headers = {
"Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
files = {
"image_file": open("image.png", "rb"),
"mask": open("mask.png", "rb"),
"prompt": (None, "Enhance brightness and remove text"),
"model": (None, "V_2")
}
response = requests.post(url, headers=headers, files=files)
print(response.json())
const formData = new FormData();
formData.append('image_file', imageFileInput.files[0]);
formData.append('mask', maskFileInput.files[0]);
formData.append('prompt', 'Enhance brightness and remove text');
formData.append('model', 'V_2');
fetch('https://gateway.pixazo.ai/ideogramV_2_Turbo/v1/edit', {
method: 'POST',
headers: {
'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
},
body: formData
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
curl -X POST "https://gateway.pixazo.ai/ideogramV_2_Turbo/v1/edit" \
-H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
-H "Content-Type: multipart/form-data" \
--form 'image_file=@/path/to/your/image.png' \
--form 'mask=@/path/to/your/mask.png' \
--form 'prompt="Enhance brightness and remove text"' \
--form 'model="V_2"'
Output
{
"created": "2024-11-01T11:46:02.294543+00:00",
"data": [
{
"is_image_safe": true,
"prompt": "replace some text",
"url": "https://ideogram.ai/api/images/ephemeral/...png"
}
]
}
Request Parameters - Edit Image
| Parameter | Required | Type | Default | Allowed values / range | Description |
|---|---|---|---|---|---|
| image_file | Yes | File | — | JPEG, PNG, WebP (max 10 MB) | The image to edit. Only JPEG, PNG, and WebP are supported; maximum size 10 MB. |
| mask | Yes | File | — | JPEG, PNG, WebP (max 10 MB) | A black-and-white mask the same size as the image. Black regions mark the areas that will be edited. |
| prompt | Yes | string | — | — | Text describing the edit to apply within the masked region. |
| model | Yes | string | — | V_2, V_2_TURBO | Model version used for editing. Edit supports only V_2 and V_2_TURBO; this Turbo endpoint uses V_2_TURBO. |
| magic_prompt_option | No | enum | AUTO | AUTO, ON, OFF | Controls whether MagicPrompt automatically enhances the prompt. |
| seed | No | integer | — | 0–2147483647 | Random seed for reproducible generation. |
| style_type | No | enum | AUTO | AUTO, GENERAL, FICTION, REALISTIC, DESIGN, RENDER_3D, ANIME | Style of the generated image. Applies to V_2 and above. |
| num_images | No | integer | 1 | 1–8 | Number of images to generate. |
Content Item Types & Limits
| Type | Max | Format / Size | Description |
|---|---|---|---|
| image | 1 | JPG, PNG, WEBP · < 10 MB | Image and mask to edit. |
Example Request
{}
Response
{
"created": "2024-11-01T11:46:02.294543+00:00",
"data": [
{
"is_image_safe": true,
"prompt": "replace some text",
"resolution": "1216x704",
"seed": 875575135,
"style_type": "GENERAL",
"url": "https://ideogram.ai/api/images/ephemeral/iSkGI5XfQ-ObReWhAiw_iA.png?exp=1730547982&sig=dabe41c3e4caa3ef788f32acc842cccfb2816686aab3e1a35d69d9139183fdc7"
}
]
}
Request Headers
| Header | Value |
|---|---|
| Ocp-Apim-Subscription-Key | YOUR_SUBSCRIPTION_KEY |
| Content-Type | multipart/form-data |
Response Handling
Common status codes for Edit Image.
| Code | Meaning |
|---|---|
| 200 | Success |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 429 | Too Many Requests |
| 500 | Internal Server Error |
Ideogram Turbo API Pricing
Ideogram Turbo API Documentation
https://gateway.pixazo.ai/ideogramV_2_Turbo/v1/remix
Remix Image - Ideogram Image Turbo API
Request Code
POST https://gateway.pixazo.ai/ideogramV_2_Turbo/v1/remix
Ocp-Apim-Subscription-Key: YOUR_Subscription_KEY
Content-Type: multipart/form-data
--boundary
Content-Disposition: form-data; name="image_request"
{"prompt":"A serene tropical beach scene. Dominating the foreground are tall palm trees with lush green leaves, standing tall against a backdrop of a sandy beach. The beach leads to the azure waters of the sea, which gently kisses the shoreline. In the distance, there is an island or landmass with a silhouette of what appears to be a lighthouse or tower. The sky above is painted with fluffy white clouds, some of which are tinged with hues of pink and orange, suggesting either a sunrise or sunset.","aspect_ratio":"ASPECT_10_16","image_weight":50,"magic_prompt_option":"ON","model":"V_2_TURBO"}
--boundary
Content-Disposition: form-data; name="image_file"; filename="image.png"
Content-Type: image/png
[binary data]
--boundary--
import requests
url = "https://gateway.pixazo.ai/ideogramV_2_Turbo/v1/remix"
headers = {
"Ocp-Apim-Subscription-Key": "YOUR_Subscription_KEY"
}
files = {
"image_request": (None, '{"prompt": "A serene tropical beach scene. Dominating the foreground are tall palm trees with lush green leaves, standing tall against a backdrop of a sandy beach. The beach leads to the azure waters of the sea, which gently kisses the shoreline. In the distance, there is an island or landmass with a silhouette of what appears to be a lighthouse or tower. The sky above is painted with fluffy white clouds, some of which are tinged with hues of pink and orange, suggesting either a sunrise or sunset.", "aspect_ratio": "ASPECT_10_16", "image_weight": 50, "magic_prompt_option": "ON", "model": "V_2_TURBO"}'),
"image_file": ("image.png", open("/path/to/your/image.png", "rb"), "image/png")
}
response = requests.post(url, headers=headers, files=files)
print(response.json())
const formData = new FormData();
formData.append('image_request', JSON.stringify({
prompt: "A serene tropical beach scene. Dominating the foreground are tall palm trees with lush green leaves, standing tall against a backdrop of a sandy beach. The beach leads to the azure waters of the sea, which gently kisses the shoreline. In the distance, there is an island or landmass with a silhouette of what appears to be a lighthouse or tower. The sky above is painted with fluffy white clouds, some of which are tinged with hues of pink and orange, suggesting either a sunrise or sunset.",
aspect_ratio: "ASPECT_10_16",
image_weight: 50,
magic_prompt_option: "ON",
model: "V_2_TURBO"
}));
formData.append('image_file', document.getElementById('imageInput').files[0]);
fetch('https://gateway.pixazo.ai/ideogramV_2_Turbo/v1/remix', {
method: 'POST',
headers: {
'Ocp-Apim-Subscription-Key': 'YOUR_Subscription_KEY'
},
body: formData
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
curl -X POST "https://gateway.pixazo.ai/ideogramV_2_Turbo/v1/remix" \
-H "Ocp-Apim-Subscription-Key: YOUR_Subscription_KEY" \
-H "Content-Type: multipart/form-data" \
--form 'image_request={
"prompt": "A serene tropical beach scene. Dominating the foreground are tall palm trees with lush green leaves, standing tall against a backdrop of a sandy beach. The beach leads to the azure waters of the sea, which gently kisses the shoreline. In the distance, there is an island or landmass with a silhouette of what appears to be a lighthouse or tower. The sky above is painted with fluffy white clouds, some of which are tinged with hues of pink and orange, suggesting either a sunrise or sunset.",
"aspect_ratio": "ASPECT_10_16",
"image_weight": 50,
"magic_prompt_option": "ON",
"model": "V_2_TURBO"
}' \
--form 'image_file=@/path/to/your/image.png'
Output
{
"created": "2000-01-23T04:56:07Z",
"data": [
{
"prompt": "A serene tropical beach scene...",
"resolution": "1024x1024",
"is_image_safe": true,
"url": "https://ideogram.ai/api/images/direct/8YEpFzHuS-S6xXEGmCsf7g"
}
]
}
Request Parameters - Remix Image
| Parameter | Required | Type | Default | Allowed values / range | Description |
|---|---|---|---|---|---|
| image_file | Yes | File | — | JPEG, PNG, WebP (max 10 MB) | The reference image to remix. Only JPEG, PNG, and WebP are supported; maximum size 10 MB. |
| image_request | Yes | JSON | — | — | A JSON string that wraps the generation parameters listed below (prompt, image_weight, aspect_ratio, model, and so on). |
| prompt | Yes | string | — | — | Within image_request. Text describing the desired output image. |
| image_weight | No | integer | 50 | 1–100 | Within image_request. How strongly the reference image influences the result; higher values stay closer to the input image. |
| aspect_ratio | No | enum | ASPECT_1_1 | ASPECT_1_1, ASPECT_10_16, ASPECT_16_10, ASPECT_9_16, ASPECT_16_9, ASPECT_3_2, ASPECT_2_3, ASPECT_4_3, ASPECT_3_4, ASPECT_1_3, ASPECT_3_1 | Within image_request. Determines the output resolution. Cannot be combined with resolution. |
| model | Yes | string | V_2_TURBO | V_2_TURBO | Within image_request. Model version used for generation. This Turbo endpoint uses V_2_TURBO. |
| magic_prompt_option | No | enum | AUTO | AUTO, ON, OFF | Within image_request. Controls whether MagicPrompt automatically enhances the prompt. |
| seed | No | integer | — | 0–2147483647 | Within image_request. Random seed for reproducible generation. |
| style_type | No | enum | AUTO | AUTO, GENERAL, FICTION, REALISTIC, DESIGN, RENDER_3D, ANIME | Within image_request. Style of the generated image. Applies to V_2 and above. |
| negative_prompt | No | string | — | — | Within image_request. Description of what to exclude from the image. |
| num_images | No | integer | 1 | 1–8 | Within image_request. Number of images to generate. |
| color_palette | No | object | — | Preset name or custom members | Within image_request. Color guidance. Use a preset name (EMBER, FRESH, JUNGLE, MAGIC, MELON, MOSAIC, PASTEL, ULTRAMARINE) or a members array of hex colors with optional weights. |
Content Item Types & Limits
| Type | Max | Format / Size | Description |
|---|---|---|---|
| image | 1 | JPG, PNG, WEBP · < 10 MB | Image to remix. |
Example Request
{
"image_request": "{\"prompt\": \"A serene tropical beach scene. Dominating the foreground are tall palm trees with lush green leaves, standing tall against a backdrop of a sandy beach. The beach leads to the azure waters of the sea, which gently kisses the shoreline. In the distance, there is an island or landmass with a silhouette of what appears to be a lighthouse or tower. The sky above is painted with fluffy white clouds, some of which are tinged with hues of pink and orange, suggesting either a sunrise or sunset.\", \"aspect_ratio\": \"ASPECT_10_16\", \"image_weight\": 50, \"magic_prompt_option\": \"ON\", \"model\": \"V_2_TURBO\"}",
"image_file": "[binary image data]"
}
Response
{
"created": "2000-01-23T04:56:07Z",
"data": [
{
"prompt": "A serene tropical beach scene. Dominating the foreground are tall palm trees with lush green leaves, standing tall against a backdrop of a sandy beach. The beach leads to the azure waters of the sea, which gently kisses the shoreline. In the distance, there's an island or landmass with a silhouette of what appears to be a lighthouse or tower. The sky above is painted with fluffy white clouds, some of which are tinged with hues of pink and orange, suggesting either a sunrise or sunset.",
"resolution": "1024x1024",
"is_image_safe": true,
"seed": 12345,
"url": "https://ideogram.ai/api/images/direct/8YEpFzHuS-S6xXEGmCsf7g",
"style_type": "REALISTIC"
}
]
}
Request Headers
| Header | Value |
|---|---|
| Ocp-Apim-Subscription-Key | YOUR_Subscription_KEY |
| Content-Type | multipart/form-data |
Response Handling
Common status codes for Remix Image.
| Code | Meaning |
|---|---|
| 200 | Success |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 429 | Too Many Requests |
| 500 | Internal Server Error |