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:
| Parameter | Required | Type | Description |
|---|---|---|---|
| prompt | Yes | string | Text describing the scene or image to be generated. |
| negative_prompt | No | string | Specifies elements or features to avoid in the image generation. |
| model | Yes | string | The version of the model to use. Currently supported value: V_2. |
| aspect_ratio | No | enum | 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 |
| seed | No | integer | Provides a random seed for reproducibility. Allowed range: 1 to 9999999999. |
| magic_prompt_option | No | enum | Controls use of MagicPrompt. Default: AUTO. Other values: ON, OFF. |
| style_type | No | enum | Specifies the style type for the image. Default: AUTO. Other values include GENERAL, REALISTIC, DESIGN, RENDER_3D, ANIME |
| color_palette | No | object | Defines 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
| Header | Description |
|---|---|
| Content-Type | application/json |
| Cache-Control | no-cache |
| Ocp-Apim-Subscription-Key | API 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 Code | Description | Response Body |
|---|---|---|
| 200 | Success - The request was successfully processed. | { "success": true, ... } |
| 400 | Bad Request - The request contains invalid parameters or missing fields. | { "error": "Invalid request parameters" } |
| 401 | Unauthorized - The provided subscription key is missing or invalid. | { "error": "Invalid or missing authentication" } |
| 403 | Forbidden - The subscription does not have access to this API or action. | { "error": "Access denied for this operation" } |
| 404 | Not Found - The requested resource or endpoint could not be found. | { "error": "Endpoint not found" } |
| 429 | Too Many Requests - The request rate limit has been exceeded. | { "error": "Rate limit exceeded, please retry later" } |
| 500 | Internal 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 |