Explore the Ideogram API Documentation for a detailed integration guide, including step-by-step instructions, code samples, and expert tips. This comprehensive resource helps you integrate Ideogram’s advanced text-to-image capabilities effortlessly into your applications, streamlining workflows and elevating user engagement with high-quality visuals.
To use this API, first, subscribe and obtain a Subscription Key, then include this key in the header of your request.
Content-Type | Set to application/json |
---|---|
Cache-Control | Recommended to set to no-cache |
Ocp-Apim-Subscription-Key | YOUR_SUBSCRIPTION_KEY |
Base URL: https://gateway.appypie.com/ideogramV_2/v1/generate
API Parameters: The API POST- https://gateway.appypie.com/ideogramV_2/v1/generate takes the following parameters:
Parameter | Type | Required | Description |
prompt | string | Yes | Text describing the scene or image to be generated. |
negative_prompt | string | Optional | Specifies elements or features to avoid in the image generation. |
model | string | Yes | The version of the model to use. Currently supported value: V_2. |
aspect_ratio | enum | Optional | Determines the image resolution. Default: ASPECT_1_1. Options include: 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 | integer | Optional | Provides a random seed for reproducibility. Allowed range: 1 to 9999999999. |
magic_prompt_option | enum | Optional | Controls use of MagicPrompt. Default: AUTO. Options include: ON, OFF, AUTO. |
style_type | enum | Optional | Specifies the style type for the image. Default: AUTO. Options include: GENERAL, REALISTIC, DESIGN, RENDER_3D, ANIME. |
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 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" } } }
POST https://gateway.appypie.com/ideogramV_2/v1/generate HTTP/1.1 Content-Type: application/json Cache-Control: no-cache { "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 urllib.request, json try: url = "https://gateway.appypie.com/ideogramV_2/v1/generate" hdr ={ # Request headers 'Content-Type': 'application/json', 'Cache-Control': 'no-cache', } # Request body data = data = json.dumps(data) req = urllib.request.Request(url, headers=hdr, data = bytes(data.encode("utf-8"))) req.get_method = lambda: 'POST' response = urllib.request.urlopen(req) print(response.getcode()) print(response.read()) except Exception as e: print(e)
// Request body const body = { "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('https://gateway.appypie.com/ideogramV_2/v1/generate', { method: 'POST', body: JSON.stringify(body), // Request headers headers: { 'Content-Type': 'application/json', 'Cache-Control': 'no-cache',} }) .then(response => { console.log(response.status); console.log(response.text()); }) .catch(err => console.error(err));
curl -v -X POST "https://gateway.appypie.com/ideogramV_2/v1/generate" -H "Content-Type: application/json" -H "Cache-Control: no-cache" --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.io.BufferedReader; import java.io.InputStreamReader; import java.net.HttpURLConnection; import java.net.URL; import java.net.URLEncoder; import java.util.HashMap; import java.util.Map; import java.io.UnsupportedEncodingException; import java.io.DataInputStream; import java.io.InputStream; import java.io.FileInputStream; public class HelloWorld { public static void main(String[] args) { try { String urlString = "https://gateway.appypie.com/ideogramV_2/v1/generate"; URL url = new URL(urlString); HttpURLConnection connection = (HttpURLConnection) url.openConnection(); //Request headers connection.setRequestProperty("Content-Type", "application/json"); connection.setRequestProperty("Cache-Control", "no-cache"); connection.setRequestMethod("POST"); // Request body connection.setDoOutput(true); connection .getOutputStream() .write( "{ \"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\" } } }".getBytes() ); int status = connection.getResponseCode(); System.out.println(status); BufferedReader in = new BufferedReader( new InputStreamReader(connection.getInputStream()) ); String inputLine; StringBuffer content = new StringBuffer(); while ((inputLine = in.readLine()) != null) { content.append(inputLine); } in.close(); System.out.println(content); connection.disconnect(); } catch (Exception ex) { System.out.print("exception:" + ex.getMessage()); } } }
$url = "https://gateway.appypie.com/ideogramV_2/v1/generate"; $curl = curl_init($url); curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "POST"); curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); # Request headers $headers = array( 'Content-Type: application/json', 'Cache-Control: no-cache',); curl_setopt($curl, CURLOPT_HTTPHEADER, $headers); # Request body $request_body = '{ "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" } } }'; curl_setopt($curl, CURLOPT_POSTFIELDS, $request_body); $resp = curl_exec($curl); curl_close($curl); var_dump($resp);
JSON
HTTP/1.1 200 OK { "created": "2024-12-17T13:49:00.587910+00:00", "data": [{ "is_image_safe": true, "prompt": "A serene tropical beach scene with tall palm trees, a sandy beach, and azure waters of the sea. The background contains an island or landmass with a silhouette of a lighthouse or tower. The sky 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", "seed": 212, "style_type": "REALISTIC", "url": "https://ideogram.ai/api/images/ephemeral/P5XmoL8mTnOmFbqCtJTguA.png?exp=1734529760&sig=b4bc813d617ccdd1c7ea435f7c861b89679e6cf9a9d349c22306cd5be63a2256" }] }
The Ideogram API offers clear HTTP status codes and detailed response messages to indicate whether a request was successfully processed or an error occurred. Implementing robust error handling ensures developers can efficiently interpret and manage API responses, enabling seamless integration and troubleshooting within their applications.
Status Code | Description | Response Body |
200 | Success - The request was successfully processed, and the image generation is in progress or completed. | { "msg": "Image Getting Created", ... } |
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" } |
{ "error": "Invalid prompt parameter" }
This Ideogram API documentation provides all the essential information needed to effectively utilize the Ideogram API. Remember to replace YOUR_API_KEY with the actual key provided upon subscribing to the service. This ensures smooth integration and optimal performance, empowering you to generate high-quality visuals effortlessly within your applications.