Ideogram API (Create Image) Documentation

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.

Authentication:

To use this API, first, subscribe and obtain a Subscription Key, then include this key in the header of your request.

Request Headers:

Content-Type Set to application/json
Cache-Control Recommended to set to no-cache
Ocp-Apim-Subscription-Key YOUR_SUBSCRIPTION_KEY

Endpoint

Base URL: https://gateway.appypie.com/ideogramV_2/v1/generate

Request Body

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.

Example Request Body

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"
            }
        }
    }
    

Request Code

Input
   
    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);
    


Response

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"
        }]
    }
    

Response Handling

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.

Common Status Codes and Responses

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" }

Example Error Response

    {
        "error": "Invalid prompt parameter"
    }
    

Conclusion

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.