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.