Ideogram API Documentation

Create Image - 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" } } }'
import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.time.Duration; public class IdeogramApi { public static void main(String[] args) throws Exception { String url = "https://gateway.pixazo.ai/ideogramV_2/v1/generate"; String json = """ { "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" } } } """; HttpClient client = HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(10)) .build(); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create(url)) .header("Content-Type", "application/json") .header("Cache-Control", "no-cache") .header("Ocp-Apim-Subscription-Key", "YOUR_SUBSCRIPTION_KEY") .POST(HttpRequest.BodyPublishers.ofString(json)) .build(); HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body()); } }
<?php $url = 'https://gateway.pixazo.ai/ideogramV_2/v1/generate'; $data = json_encode([ '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' ] ] ]); $ch = curl_init($url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, $data); curl_setopt($ch, CURLOPT_HTTPHEADER, [ 'Content-Type: application/json', 'Cache-Control: no-cache', 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' ]); $response = curl_exec($ch); curl_close($ch); echo $response; ?>

Output

Successful API response:

{ "created": "2024-11-01T10:06:14.744267+00:00", "data": [ { "is_image_safe": true, "prompt": "A serene tropical beach...", "resolution": "800x1280", "seed": 212, "style_type": "REALISTIC", "url": "https://ideogram.ai/api/images/ephemeral/4p6cIwykSjaWcUUavtwuMw.png?exp=1730541994&sig=ef2b2872a29327783454a41061d1e890361cb6a5c77c358c6190793095428b59" } ] }

Request Body - Create Image

Parameters for /generate:

ParameterRequiredTypeDescription
promptYesstringText describing the scene or image to be generated.
negative_promptNostringSpecifies elements or features to avoid in the image generation.
modelYesstringThe version of the model to use. Currently supported value: V_2.
aspect_ratioNoenumDetermines 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
seedNointegerProvides a random seed for reproducibility. Allowed range: 1 to 9999999999.
magic_prompt_optionNoenumControls use of MagicPrompt. Default: AUTO. Other values: ON, OFF.
style_typeNoenumSpecifies the style type for the image. Default: AUTO. Other values include GENERAL, REALISTIC, DESIGN, RENDER_3D, ANIME
color_paletteNoobjectDefines a color palette using a preset name. Available presets: EMBER, FRESH, JUNGLE, MAGIC, MELON, MOSAIC, PASTEL, ULTRAMARINE

Example Request - Create Image

JSON
{ "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 - Create Image

JSON
{ "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

HeaderDescription
Content-Typeapplication/json
Cache-Controlno-cache
Ocp-Apim-Subscription-KeyAPI subscription key for authentication

Response Handling

The Ideogram Generate returns specific HTTP status codes and response bodies to indicate the success or failure of a request. Developers should implement error handling in their applications to manage these responses effectively.

Common Status Codes and Responses

Status CodeDescriptionResponse Body
200Success - The request was successfully processed.{ "success": true, ... }
Bad Request - The request contains invalid parameters or missing fields.{ "error": "Invalid request parameters" }
401Unauthorized - The provided subscription key is missing or invalid.{ "error": "Invalid or missing authentication" }
403Forbidden - The subscription does not have access to this API or action.{ "error": "Access denied for this operation" }
404Not Found - The requested resource or endpoint could not be found.{ "error": "Endpoint not found" }
Too Many Requests - The request rate limit has been exceeded.{ "error": "Rate limit exceeded, please retry later" }
500Internal Server Error - An unexpected error occurred on the server.{ "error": "An unexpected error occurred, please try again later" }

Example Error Response

{ "error": "Invalid parameters" }

Retrieving Image Result and URL

After submitting your request, use this endpoint to check status and retrieve results.

Endpoint

POST https://gateway.pixazo.ai/ai-model-api-polling/getGenerationResults

Request Body

{ "job_set_id": "your-job-set-id-here" }

Example Request Headers

Content-Type: application/json Cache-Control: no-cache Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

Example Response

{ "job_set_id": "your-job-set-id-here", "status": "completed", "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" } ] }

HTTP Example

POST https://gateway.pixazo.ai/ai-model-api-polling/getGenerationResults Content-Type: application/json Cache-Control: no-cache Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY { "job_set_id": "your-job-set-id-here" }

Python Example

import requests import json url = "https://gateway.pixazo.ai/ai-model-api-polling/getGenerationResults" headers = { "Content-Type": "application/json", "Cache-Control": "no-cache", "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY" } data = { "job_set_id": "your-job-set-id-here" } response = requests.post(url, headers=headers, json=data) print(response.json())

JavaScript Example

const url = 'https://gateway.pixazo.ai/ai-model-api-polling/getGenerationResults'; const headers = { 'Content-Type': 'application/json', 'Cache-Control': 'no-cache', 'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY' }; const data = { job_set_id: 'your-job-set-id-here' }; 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 Example

curl -v -X POST "https://gateway.pixazo.ai/ai-model-api-polling/getGenerationResults" \ -H "Content-Type: application/json" \ -H "Cache-Control: no-cache" \ -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \ --data-raw '{ "job_set_id": "your-job-set-id-here" }'

Java Example

import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.time.Duration; public class IdeogramPolling { public static void main(String[] args) throws Exception { String url = "https://gateway.pixazo.ai/ai-model-api-polling/getGenerationResults"; String json = """ { "job_set_id": "your-job-set-id-here" } """; HttpClient client = HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(10)) .build(); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create(url)) .header("Content-Type", "application/json") .header("Cache-Control", "no-cache") .header("Ocp-Apim-Subscription-Key", "YOUR_SUBSCRIPTION_KEY") .POST(HttpRequest.BodyPublishers.ofString(json)) .build(); HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body()); } }

PHP Example

<?php $url = 'https://gateway.pixazo.ai/ai-model-api-polling/getGenerationResults'; $data = json_encode([ 'job_set_id' => 'your-job-set-id-here' ]); $ch = curl_init($url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, $data); curl_setopt($ch, CURLOPT_HTTPHEADER, [ 'Content-Type: application/json', 'Cache-Control: no-cache', 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' ]); $response = curl_exec($ch); curl_close($ch); echo $response; ?>

Ideogram API Pricing

Resolution Price (USD)
All Resolution$0.2