> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ideogram AI Drawing

## Ideogram V3 Interface

Ideogram V3 model provides advanced image generation and processing capabilities. The V3 interface differs from previous versions in parameters and usage, and this section will detail the V3 interfaces and usage examples.

### V3 Generate

`POST` [https://aihubmix.com/ideogram/v1/ideogram-v3/generate](https://aihubmix.com/ideogram/v1/ideogram-v3/generate)

Generate images based on given prompts. The V3 model provides higher quality image generation capabilities, supporting more diverse styles and parameter controls.

<ParamField body="prompt" type="string" required>
  Prompt for image generation
</ParamField>

<ParamField body="rendering_speed" default="DEFAULT" type="string">
  Rendering speed options, available `TURBO`, `DEFAULT`, `QUALITY`
</ParamField>

<ParamField body="num_images" default="1" type="integer">
  Number of images to generate, range 1-8\
  Generating more images will not significantly increase the generation time
</ParamField>

<ParamField body="aspect_ratio" default="1x1" type="string">
  Aspect ratio for image generation, supports a wide range of specifications\
  Available \['1x3', '3x1', '1x2', '2x1', '9x16', '16x9', '10x16', '16x10', '2x3', '3x2', '3x4', '4x3', '4x5', '5x4', '1x1']\
  The aspect ratios used in different models are different.
</ParamField>

<ParamField body="magic_prompt" default="AUTO" type="string">
  Prompt enhancement. Available parameters: `AUTO`, `ON`, `OFF`
</ParamField>

<ParamField body="style_type" default="AUTO" type="string">
  Style type for image generation, available `AUTO`, `GENERAL`, `REALISTIC`, `DESIGN`\
  Note: Compared to V2 version, the type is more focused
</ParamField>

<ParamField body="negative_prompt" type="string">
  Description of content you do not want to appear in the image
</ParamField>

<ParamField body="seed" type="integer">
  Random seed, range: 0-2147483647\
  Do not use seed when generating multiple images, otherwise the same image will be generated
</ParamField>

<ParamField body="style_reference_images" type="file">
  Style reference image, can be used for style guidance
</ParamField>

### Usage Examples

<CodeGroup>
  ```shell Curl Text-to-Image theme={null}
  curl -X POST https://aihubmix.com/ideogram/v1/ideogram-v3/generate \
    -H "Api-Key: sk-***" \
    -H "Content-Type: multipart/form-data" \
    -F prompt="Delicate 3D cover design with various combat machines flying from an portal. The machines have different shapes, sizes, and colors. The portal is emitting swirling energy. The background contains a futuristic city with tall buildings. The text \"One Gateway, Infinite Models\" is placed in the center with neon lights, expansive view, cinematic lighting, vivid color, bright tone. clean text, cyber punk, smooth render" \
    -F rendering_speed="QUALITY" \
    -F num_images="2" \
    -F aspect_ratio="2x1"
  ```

  ```py Python Text-to-Image theme={null}
  import requests
  import os

  # Prepare request data - use dictionary instead of JSON
  data = {
    "prompt": "Delicate 3D cover design with various combat machines flying from an portal. The machines have different shapes, sizes, and colors. The portal is emitting swirling energy. The background contains a futuristic city with tall buildings. The text \"One Gateway, Infinite Models\" is placed in the center with neon lights, expansive view, cinematic lighting, vivid color, bright tone. clean text, cyber punk, smooth render",
    "rendering_speed": "QUALITY",
    "num_images": "2",
    "aspect_ratio": "2x1",
    "magic_prompt": "AUTO",
    "style_type": "AUTO",
    "negative_prompt": "blurry, watermark"
  }

  # Content-Type is multipart/form-data
  files = {}
  for key, value in data.items():
      files[key] = (None, str(value))  # Send each data field as a form field

  response = requests.post(
    "https://aihubmix.com/ideogram/v1/ideogram-v3/generate",
    headers={
      "Api-Key": "sk-***" # Replace with your AiHubMix API key
    },
    files=files
  )
  print(response.json())

  # save output image to file
  response_json = response.json()
  if response.ok and 'data' in response_json and len(response_json['data']) > 0:
      image_data = response_json['data'][0]['url']
      image_response = requests.get(image_data)
      if image_response.ok:
          with open('output.png', 'wb') as f:
              f.write(image_response.content)
          print("Image saved to output.png")
      else:
          print(f"Failed to get image: {image_response.status_code}")
  else:
      print("API request failed or no image returned")
  ```

  ```py Python Reference Image + Text-to-Image theme={null}
  import requests
  import os

  data = {
    "prompt": "Delicate 3D cover design with various combat machines flying from an portal. The machines have different shapes, sizes, and colors. The portal is emitting swirling energy. The background contains a futuristic city with tall buildings. The text \"One Gateway, Infinite Models\" is placed in the center with neon lights, expansive view, cinematic lighting, vivid color, bright tone. clean text, cyber punk, smooth render",
    "rendering_speed": "QUALITY",
    "num_images": 2,
    # "seed": "998", # DO NOT use seed when generating multiple images
    "aspect_ratio": "2x1", 
    "magic_prompt": "AUTO",
    "style_type": "AUTO",
    "negative_prompt": "blurry, watermark",
  }

  # initialize files parameter
  files = None

  # Style reference image path
  style_reference_path = "yourpath/reference-image.jpeg"
  use_reference_image = True

  if use_reference_image and os.path.exists(style_reference_path):
      # If using a reference image and the file exists, set the files parameter
      files = [
          ("style_reference_images", open(style_reference_path, "rb")),
          # If you need to add multiple style reference images, you can add them as follows:
          # ("style_reference_images", open("Second reference image path", "rb")),
      ]
  elif use_reference_image:
      print(f"Warning: Style reference image not found: {style_reference_path}")

  response = requests.post(
    "https://aihubmix.com/ideogram/v1/ideogram-v3/generate",
    headers={
      "Api-Key": "sk-***" # Replace with your AiHubMix API key
    },
    data=data,
    files=files
  )
  print(response.json())

  # save output image to file
  response_json = response.json()
  if response.ok and 'data' in response_json and len(response_json['data']) > 0:
      image_data = response_json['data'][0]['url']
      image_response = requests.get(image_data)
      if image_response.ok:
          with open('output.png', 'wb') as f:
              f.write(image_response.content)
          print("Image saved to output.png")
      else:
          print(f"Failed to get image: {image_response.status_code}")
  else:
      print("API request failed or no image returned")
  ```
</CodeGroup>

### V3 Remix

`POST` [https://aihubmix.com/ideogram/v1/ideogram-v3/remix](https://aihubmix.com/ideogram/v1/ideogram-v3/remix)

Remix images based on a reference image and prompt. The Remix function of V3 has better retention of the style and content of the original image.

<ParamField body="prompt" type="string" required>
  Prompt for image remixing
</ParamField>

<ParamField body="image" type="file" required>
  Original image file
</ParamField>

<ParamField body="image_weight" default="50" type="integer">
  The weight of the original image, range 1-100, the larger the value, the more similar the result to the original image.
</ParamField>

<ParamField body="rendering_speed" default="DEFAULT" type="string">
  Rendering speed options, available `TURBO`, `DEFAULT`, `QUALITY`
</ParamField>

<ParamField body="num_images" default="1" type="integer">
  Number of images to generate, range 1-8
  Generating more images will not significantly increase the generation time
</ParamField>

<ParamField body="aspect_ratio" type="string">
  Aspect ratio of the output image, available \['1x3', '3x1', '1x2', '2x1', '9x16', '16x9', '10x16', '16x10', '2x3', '3x2', '3x4', '4x3', '4x5', '5x4', '1x1']
</ParamField>

<ParamField body="style_reference_images" type="file">
  Style reference image, can be used for style guidance
</ParamField>

<ParamField body="seed" type="integer">
  Random seed, range: 0-2147483647
</ParamField>

<ParamField body="magic_prompt" default="AUTO" type="string">
  Prompt enhancement. Available parameters: `AUTO`, `ON`, `OFF`
</ParamField>

<ParamField body="style_type" default="AUTO" type="string">
  Style type for image generation, available `AUTO`, `GENERAL`, `REALISTIC`, `DESIGN`
</ParamField>

<ParamField body="negative_prompt" type="string">
  Description of content you do not want to appear in the image
</ParamField>

### Usage Examples

<CodeGroup>
  ```py Python Remix theme={null}
  import requests
  import os

  data = {
    "prompt": "bird playing with a cat in the snow, pixel art style",
    "image_weight": "60",
    "rendering_speed": "QUALITY",
    "num_images": 1,
    "seed": 1,
    "aspect_ratio": "16x9", 
    "magic_prompt": "AUTO",
    "style_type": "AUTO",
    "negative_prompt": "blurry, bad anatomy, watermark",
  }

  # Original image - required
  source_image_path = "yourpath/image.jpeg"
  if not os.path.exists(source_image_path):
      raise FileNotFoundError(f"Original image not found: {source_image_path}")

  # initialize files parameter
  files = None

  # Style reference image path
  style_reference_path = "yourpath/reference-image.png"
  use_reference_image = True

  # Prepare the files for upload
  with open(source_image_path, "rb") as image_file:
      if use_reference_image and os.path.exists(style_reference_path):
          # If using a reference image and the file exists, set the files parameter
          files = {
              "image": image_file,
              "style_reference_images": open(style_reference_path, "rb"),
          }
      else:
          if use_reference_image:
              print(f"Warning: Style reference image not found: {style_reference_path}")
          files = {
              "image": image_file,
          }

      response = requests.post(
        "https://aihubmix.com/ideogram/v1/ideogram-v3/remix",
        headers={
          "Api-Key": "sk-***" # Replace with your AiHubMix API key
        },
        data=data,
        files=files
      )
  print(response.json())

  # save output image to file
  response_json = response.json()
  if response.ok and 'data' in response_json and len(response_json['data']) > 0:
      image_data = response_json['data'][0]['url']
      image_response = requests.get(image_data)
      if image_response.ok:
          with open('output.png', 'wb') as f:
              f.write(image_response.content)
          print("Image saved to output.png")
      else:
          print(f"Failed to get image: {image_response.status_code}")
  else:
      print("API request failed or no image returned")
      print(f"Error details: {response_json}")
  ```
</CodeGroup>

### V3 Edit

`POST` [https://aihubmix.com/ideogram/v1/ideogram-v3/edit](https://aihubmix.com/ideogram/v1/ideogram-v3/edit)

The local editing function of V3 allows users to precisely edit specific areas of an image by providing the original image and mask, while keeping other areas unchanged.

<ParamField body="prompt" type="string" required>
  Prompt for image editing
</ParamField>

<ParamField body="image" type="file" required>
  Original image file
</ParamField>

<ParamField body="mask" type="file" required>
  Mask image, black area represents the part to be edited, white area represents the part to be kept unchanged
</ParamField>

<ParamField body="rendering_speed" default="DEFAULT" type="string">
  Rendering speed options, available `TURBO`, `DEFAULT`, `QUALITY`
</ParamField>

<ParamField body="num_images" default="1" type="integer">
  Number of images to generate, range 1-8
  Generating more images will not significantly increase the generation time
</ParamField>

<ParamField body="aspect_ratio" type="string">
  Aspect ratio of the output image, available \['1x3', '3x1', '1x2', '2x1', '9x16', '16x9', '10x16', '16x10', '2x3', '3x2', '3x4', '4x3', '4x5', '5x4', '1x1']
</ParamField>

<ParamField body="seed" type="integer">
  Random seed, range: 0-2147483647
</ParamField>

<ParamField body="magic_prompt" default="AUTO" type="string">
  Prompt enhancement. Available parameters: `AUTO`, `ON`, `OFF`
</ParamField>

<ParamField body="style_type" default="AUTO" type="string">
  Style type for image generation, available `AUTO`, `GENERAL`, `REALISTIC`, `DESIGN`
</ParamField>

<ParamField body="negative_prompt" type="string">
  Description of content you do not want to appear in the image
</ParamField>

### Usage Examples

<CodeGroup>
  ```py Python Edit theme={null}
  import requests
  import os

  # Original image - required
  source_image_path = "yourpath/image.jpeg"
  # mask - required
  mask_image_path = "yourpath/mask.jpg"

  if not os.path.exists(source_image_path):
      raise FileNotFoundError(f"Original image not found: {source_image_path}")

  with open(source_image_path, "rb") as image_file, open(mask_image_path, "rb") as mask_file:
      response = requests.post(
          "https://aihubmix.com/ideogram/v1/ideogram-v3/edit",
          headers={
              "Api-Key": "sk-***" # Replace with your AiHubMix API key
          },
          data={
              "prompt": "remove text",
              "rendering_speed": "DEFAULT",
              "num_images": 1,
              "seed": 1,
              "aspect_ratio": "16x9",
              "magic_prompt": "AUTO",
              "style_type": "AUTO",
              "negative_prompt": "blurry, bad anatomy, watermark",
          },
          files={
              "image": image_file,
              "mask": mask_file,
          }
      )

  print(response.json())

  # save output image to file
  response_json = response.json()
  if response.ok and 'data' in response_json and len(response_json['data']) > 0:
      image_data = response_json['data'][0]['url']
      image_response = requests.get(image_data)
      if image_response.ok:
          with open('output.png', 'wb') as f:
              f.write(image_response.content)
          print("Image saved to output.png")
      else:
          print(f"Failed to get image: {image_response.status_code}")
  else:
      print("API request failed or no image returned")
      print(f"Error details: {response_json}")
  ```
</CodeGroup>

### V3 Replace Background

`POST` [https://aihubmix.com/ideogram/v1/ideogram-v3/replace-background](https://aihubmix.com/ideogram/v1/ideogram-v3/replace-background)

V3 的背景替换功能可以智能地识别图像的前景和背景，并根据提示词替换背景，同时保持前景对象不变。

<ParamField body="prompt" type="string" required>
  Prompt for background replacement
</ParamField>

<ParamField body="image" type="file" required>
  Original image file
</ParamField>

<ParamField body="rendering_speed" default="DEFAULT" type="string">
  Rendering speed options, available `TURBO`, `DEFAULT`, `QUALITY`
</ParamField>

<ParamField body="num_images" default="1" type="integer">
  Number of images to generate, range 1-8
  Generating more images will not significantly increase the generation time
</ParamField>

<ParamField body="style_reference_images" type="file">
  Style reference image, can be used for style guidance
</ParamField>

<ParamField body="seed" type="integer">
  Random seed, range: 0-2147483647
</ParamField>

<ParamField body="magic_prompt" default="AUTO" type="string">
  Prompt enhancement. Available parameters: `AUTO`, `ON`, `OFF`
</ParamField>

<ParamField body="style_type" default="AUTO" type="string">
  Style type for image generation, available `AUTO`, `GENERAL`, `REALISTIC`, `DESIGN`
</ParamField>

### Usage Examples

<CodeGroup>
  ```py Python Replace Background theme={null}
  import requests
  import os

  data = {
    "prompt": "bird playing with a cat in the snow, pixel art style",
    "rendering_speed": "QUALITY",
    "num_images": 1,
    "seed": 1,
    # no "aspect_ratio"
    "magic_prompt": "AUTO",
    "style_type": "AUTO",
    # no "negative_prompt"
  }

  # Original image - required
  source_image_path = "yourpath/image.png"
  if not os.path.exists(source_image_path):
      raise FileNotFoundError(f"Original image not found: {source_image_path}")

  # initialize files parameter
  files = None

  # Style reference image path
  style_reference_path = "yourpath/reference-image.png"
  use_reference_image = True

  # Prepare files
  with open(source_image_path, "rb") as image_file:
      if use_reference_image and os.path.exists(style_reference_path):
          # If using a reference image and the file exists, set the files parameter
          files = {
              "image": image_file,
              "style_reference_images": open(style_reference_path, "rb"),
          }
      else:
          if use_reference_image:
              print(f"Warning: Style reference image not found: {style_reference_path}")
          files = {
              "image": image_file,
          }

      response = requests.post(
        "https://aihubmix.com/ideogram/v1/ideogram-v3/replace-background",
        headers={
          "Api-Key": "sk-***" # Replace with your AiHubMix API key
        },
        data=data,
        files=files
      )
  print(response.json())

  # save output image to file
  response_json = response.json()
  if response.ok and 'data' in response_json and len(response_json['data']) > 0:
      image_data = response_json['data'][0]['url']
      image_response = requests.get(image_data)
      if image_response.ok:
          with open('output.png', 'wb') as f:
              f.write(image_response.content)
          print("Image saved to output.png")
      else:
          print(f"Failed to get image: {image_response.status_code}")
  else:
      print("API request failed or no image returned")
      print(f"Error details: {response_json}")
  ```
</CodeGroup>

For more optional parameters, please refer to [Ideogram AI](https://developer.ideogram.ai/api-reference/api-reference/generate-v3)

### 💰 V3 Pricing

| Ideogram v3 | Generate  | Remix     | Edit      | Reframe   | Replace BG |
| ----------- | --------- | --------- | --------- | --------- | ---------- |
| 3.0 Turbo   | US \$0.03 | US \$0.03 | US \$0.03 | US \$0.03 | US \$0.03  |
| 3.0 Default | US \$0.06 | US \$0.06 | US \$0.06 | US \$0.06 | US \$0.06  |
| 3.0 Quality | US \$0.09 | US \$0.09 | US \$0.09 | US \$0.09 | US \$0.09  |

***

## V2 & V1 Interface Description

Ideogram AI V2 & V1 drawing interface with strong text-to-image capabilities, including generate, remix, edit, upscale, and describe functionalities.

* **Remix:** Create new images based on a reference image and prompt.
* **Edit:** Make local edits to specific areas of a reference image using prompts and masks.
* **Upscale:** Enhance low-resolution images to high-resolution, with control over similarity and detail levels.
* **Describe:** Reverse-engineering prompts to describe images.

**Supported Styles:**

* AUTO: Default automatic selection
* GENERAL: General purpose
* REALISTIC: Realistic
* DESIGN: Design-oriented
* RENDER\_3D: 3D rendering
* ANIME: Anime style

<Warning>
  1. Available through the official AiHubMix API or [Cherry Studio APP](https://cherry-ai.com/). Note that currently a proxy is required for image generation; direct connection within China will be supported in the future.
  2. Cherry Studio currently only offers the Ideogram drawing (generate) interface.
</Warning>

### Generate

`POST` [https://aihubmix.com/ideogram/generate](https://api.aihubmix.com/ideogram/generate)\
Synchronously generates images based on given prompts and optional parameters. Image links have a limited validity period; if you want to keep the images, you must download and save them.

**Request Parameters**

<ParamField body="image_request" type="object" required>
  Request object for image generation
</ParamField>

<ParamField body="image_request.prompt" type="string" required>
  Prompt for image generation
</ParamField>

<ParamField body="image_request.aspect_ratio" default="ASPECT_1_1" type="string">
  Aspect ratio for image generation, determines the resolution. Cannot be used with resolution parameter.

  Available ratios:

  * ASPECT\_1\_1
  * ASPECT\_3\_1
  * ASPECT\_1\_3
  * ASPECT\_3\_2
  * ASPECT\_2\_3
  * ASPECT\_4\_3
  * ASPECT\_3\_4
  * ASPECT\_16\_9
  * ASPECT\_9\_16
  * SPECT\_16\_10
  * ASPECT\_10\_16
</ParamField>

<ParamField body="image_request.model" default="V_2" type="string">
  Model for generating or editing images. /generate and /remix support all model types, but /edit only supports V\_2 and V\_2\_TURBO.

  Available model versions:

  * V\_1
  * V\_1\_TURBO
  * V\_2
  * V\_2\_TURBO
  * V\_2A
  * V\_2A\_TURBO
</ParamField>

<ParamField body="image_request.magic_prompt_option" default="AUTO" type="string">
  Prompt enhancement option. Available parameters: AUTO, ON, OFF
</ParamField>

<ParamField body="image_request.seed" type="integer">
  Random seed, range: 0-2147483647
</ParamField>

<ParamField body="image_request.style_type" default="AUTO" type="string">
  Style type used for generating images; this parameter only applies to V\_2 and higher versions of the model and should not be specified in V\_1 versions.

  Available styles:

  * AUTO
  * GENERAL
  * REALISTIC
  * DESIGN
  * RENDER\_3D
  * ANIME
</ParamField>

<ParamField body="image_request.negative_prompt" type="string">
  Describes what you don't want to appear in the image. Only applicable to model versions V\_1, V\_1\_TURBO, V\_2, and V\_2\_TURBO. Descriptions in the prompt take precedence over descriptions in the negative prompt.
</ParamField>

<ParamField body="image_request.num_images" default="1" type="integer">
  Number of images to generate, range 1-8
</ParamField>

<ParamField body="image_request.resolution" type="string">
  Resolution for image generation (only applicable to model version 2.0, cannot be used with aspect\_ratio), expressed as width x height. If not specified, aspect\_ratio is used by default.
</ParamField>

### Example Calls

<CodeGroup>
  ```py Python theme={null}
  import requests
  import os

  url = "https://aihubmix.com/ideogram/generate"

  payload = { "image_request": {
          "prompt": "3D cartoon, An adorable white owl baby with tilted head, shiny amber eyes with highlight, fluffy body, standing on a trunk with moss and lots of glowing mushrooms, Close up, cinematic lighting, low angle, deep sense of depth. The background is a magical spring landscape, cute and esthetic, huge title design \"Always curious\"", #string optional
          "negative_prompt": "blurry, bad anatomy, watermark",
          "aspect_ratio": "ASPECT_3_2",  # optional include ASPECT_1_1(Default), ASPECT_3_2, ASPECT_2_3, ASPECT_4_3, ASPECT_3_4, ASPECT_16_9, ASPECT_9_16, SPECT_16_10, ASPECT_10_16
          "model": "V_2",
          "num_images": 2, #integer optional >=1 <=8 Defaults to 1
          "magic_prompt_option": "AUTO", #string optional AUTO, ON, OFF
          #"seed": "2" #integer optional >=0 <=2147483647
          "style_type": "RENDER_3D" #string optional AUTO/GENERAL/REALISTIC/DESIGN/RENDER_3D/ANIME, only applicable to V_2 and above
      } }
  headers = {
      "Api-Key": os.getenv("AIHUBMIX_API_KEY"),
      "Content-Type": "application/json"
  }

  response = requests.post(url, json=payload, headers=headers)

  print(response.json())
  ```

  ```js Javascript theme={null}
  const url = 'https://aihubmix.com/ideogram/describe';
  const form = new FormData();
  form.append('image_file', '<file1>');

  const options = {method: 'POST', headers: {'Api-Key': '<apiKey>'}};

  options.body = form;

  try {
    const response = await fetch(url, options);
    const data = await response.json();
    console.log(data);
  } catch (error) {
    console.error(error);
  }
  ```

  ```shell Curl theme={null}
  curl -X POST https://aihubmix.com/ideogram/generate \
       -H "Api-Key: <apiKey>" \
       -H "Content-Type: application/json" \
       -d '{
    "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.",
      "aspect_ratio": "ASPECT_10_16",
      "model": "V_2",
      "magic_prompt_option": "AUTO"
    }
  }'
  ```
</CodeGroup>

### Response

Image(s) generated successfully.

```json theme={null}
{
  "created": "2000-01-23T04:56:07Z",
  "data": [
    {
      "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's 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.",
      "resolution": "1024x1024",
      "is_image_safe": true,
      "seed": 12345,
      "url": "https://ideogram.ai/api/images/direct/8YEpFzHuS-S6xXEGmCsf7g",
      "style_type": "REALISTIC"
    }
  ]
}
```

### Error Codes

* `400` : Post Generate Image Request Bad Request Error
* `401` : Post Generate Image Request Unauthorized Error
* `422` : Post Generate Image Request Unprocessable Entity Error
* `429` : Post Generate Image Request Too Many Requests Error

### Edit

`POST` [https://aihubmix.com/ideogram/edit](https://api.aihubmix.com/ideogram/edit)

Synchronously edits a specified image using the provided mask. The mask indicates which parts of the image should be edited, while the prompt and selected style type can further guide the editing direction. Supported image formats include JPEG, PNG, and WebP. Image links have a limited validity period; if you want to keep the images, you must download and save them.

**Request Parameters**

<ParamField body="image_file" type="file" required>
  Original image file, supports JPEG, PNG, and WebP formats
</ParamField>

<ParamField body="mask" type="file" required>
  Mask image, must meet the following requirements:

  * Contains only black and white pixels, supports RGB, RGBA, or grayscale image formats
  * Exactly the same dimensions as the original image
  * Black areas represent parts that need to be modified, white areas represent parts that need to remain unchanged
  * Cannot be pure white
  * The modified area (black part) should occupy at least 10% of the image area
</ParamField>

<ParamField body="prompt" type="string" required>
  Prompt for local editing
</ParamField>

<ParamField body="model" type="string" required>
  Model for generating or editing images. /generate and /remix support all model types, but /edit only supports V\_2 and V\_2\_TURBO.

  Available model versions:

  * V\_2
  * V\_2\_TURBO
</ParamField>

<ParamField body="magic_prompt_option" default="AUTO" type="string">
  Prompt enhancement option. Available parameters: AUTO, ON, OFF
</ParamField>

<ParamField body="num_images" default="1" type="integer">
  Number of images to generate, range 1-8
</ParamField>

<ParamField body="seed" type="integer">
  Random seed, range: 0-2147483647
</ParamField>

<ParamField body="style_type" default="AUTO" type="string">
  Style type used for generating images; this parameter only applies to V\_2 and higher versions of the model.

  Available styles:

  * AUTO
  * GENERAL
  * REALISTIC
  * DESIGN
  * RENDER\_3D
  * ANIME
</ParamField>

### Example Calls

<CodeGroup>
  ```py Python theme={null}
  import requests
  import os

  url = "https://aihubmix.com/ideogram/eidt"

  files = {
      "image_file": open('<file1>', 'rb'), #required
      "mask": "open('<file1>', 'rb')" #required
  }

  payload = {
      "prompt": "\"prompt\"", #required
      "model": "V_2",  #required, only supported for V_2 and V_2_TURBO.
      "magic_prompt_option": ,
      "num_images":1, #integer optional >=1 <=8 Defaults to 1
      "seed": , #integer optional >=0 <=2147483647
      "style_type":
  16}
  headers = {"Api-Key": os.getenv("AIHUBMIX_API_KEY")}

  response = requests.post(url, data=payload, files=files, headers=headers)

  print(response.json()

  # close file
  files["image_file"].close()
  files["mask"].close()
  ```

  ```js Javascript theme={null}
  const url = 'https://aihubmix.com/ideogram/edit';
  const form = new FormData();
  form.append('image_file', '<file1>');
  form.append('mask', '<file1>');
  form.append('prompt', '"prompt"');
  form.append('model', '"V_1"');
  form.append('magic_prompt_option', '');
  form.append('num_images', '');
  form.append('seed', '');
  form.append('style_type', '');

  const options = {method: 'POST', headers: {'Api-Key': '<apiKey>'}};

  options.body = form;

  try {
    const response = await fetch(url, options);
    const data = await response.json();
    console.log(data);
  } catch (error) {
    console.error(error);
  }
  ```

  ```shell Curl theme={null}
  curl -X POST https://aihubmix.com/ideogram/edit \
       -H "Api-Key: <apiKey>" \
       -H "Content-Type: multipart/form-data" \
       -F image_file=@<file1> \
       -F mask=@<file1> \
       -F prompt="prompt" \
       -F model="V_1"
  ```
</CodeGroup>

### Response

Image edits generated successfully.

```json theme={null}
{
  "created": "2000-01-23T04:56:07Z",
  "data": [
    {
      "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's 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.",
      "resolution": "1024x1024",
      "is_image_safe": true,
      "seed": 12345,
      "url": "https://ideogram.ai/api/images/direct/8YEpFzHuS-S6xXEGmCsf7g",
      "style_type": "REALISTIC"
    }
  ]
}
```

### Error Codes

* `400` : Post Edit Image Request Bad Request Error
* `401` : Post Edit Image Request Unauthorized Error
* `422` : Post Edit Image Request Unprocessable Entity Error
* `429` : Post Edit Image Request Too Many Requests Error

### Remix

`POST` [https://aihubmix.com/ideogram/remix](https://api.aihubmix.com/ideogram/remix)

Fuses the provided image with given prompts and optional parameters. Input images are cropped to the selected aspect ratio before remixing. Supported image formats include JPEG, PNG, and WebP. Image links have a limited validity period; if you want to keep the images, you must download and save them.

**Request Parameters**

<ParamField body="image_request" type="object" required>
  Request to generate new images using the provided image and prompt. The provided image will be cropped to match the selected output aspect ratio.
</ParamField>

<ParamField body="image_request.prompt" type="string" required>
  Prompt for image generation
</ParamField>

<ParamField body="image_request.aspect_ratio" default="ASPECT_1_1" type="string">
  Aspect ratio for image generation, determines the resolution. Cannot be used with resolution parameter.

  Available ratios:

  * ASPECT\_1\_1
  * ASPECT\_3\_1
  * ASPECT\_1\_3
  * ASPECT\_3\_2
  * ASPECT\_2\_3
  * ASPECT\_4\_3
  * ASPECT\_3\_4
  * ASPECT\_16\_9
  * ASPECT\_9\_16
  * SPECT\_16\_10
  * ASPECT\_10\_16
</ParamField>

<ParamField body="image_request.image_weight" default="50" type="integer">
  Reference image weight, range: 1-100
</ParamField>

<ParamField body="image_request.model" default="V_2" type="string">
  Model for generating or editing images. /generate and /remix support all model types, but /edit only supports V\_2 and V\_2\_TURBO.
</ParamField>

<ParamField body="image_request.negative_prompt" type="string">
  Describes what you don't want to appear in the image. Only applicable to model versions V\_1, V\_1\_TURBO, V\_2, and V\_2\_TURBO. Descriptions in the prompt take precedence over descriptions in the negative prompt.
</ParamField>

<ParamField body="image_request.magic_prompt_option" default="AUTO" type="string">
  Prompt enhancement option. Available parameters: AUTO, ON, OFF
</ParamField>

<ParamField body="image_request.num_images" default="1" type="integer">
  Number of images to generate, range: 1-8
</ParamField>

<ParamField body="image_request.resolution" type="string">
  Resolution for image generation (only applicable to model version 2.0, cannot be used with aspect\_ratio), expressed as width x height. If not specified, aspect\_ratio is used by default.
</ParamField>

<ParamField body="image_request.seed" type="integer">
  Random seed, range: 0-2147483647
</ParamField>

<ParamField body="image_request.style_type" default="AUTO" type="string">
  Style type for generated images; only applicable to V\_2 and higher versions of models, should not be specified in V\_1 versions.

  Available styles:

  * AUTO
  * GENERAL
  * REALISTIC
  * DESIGN
  * RENDER\_3D
  * ANIME
</ParamField>

<ParamField body="image_file" type="file" required>
  Original image file, supports JPEG, PNG, and WebP formats
</ParamField>

### Example Calls

<CodeGroup>
  ```py Python theme={null}
  import requests
  import os

  url = "https://aihubmix.com/ideogram/remix"

  files = { "image_file": open('<file1>', 'rb') }
  payload = {"image_request": '''{
      "prompt": "watercolor",
      "aspect_ratio": "ASPECT_10_16",
      "image_weight": 50,
      "magic_prompt_option": "ON",
      "model": "V_2"
  }'''}

  headers = {"Api-Key": os.getenv("AIHUBMIX_API_KEY")}

  response = requests.post(url, data=payload, files=files, headers=headers)

  print(response.json())
  ```

  ```js Javascript theme={null}
  const url = 'https://aihubmix.com/ideogram/remix';
  const form = new FormData();
  form.append('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.",
    "aspect_ratio": "ASPECT_10_16",
    "image_weight": 50,
    "magic_prompt_option": "ON",
    "model": "V_2"
  }');
  form.append('image_file', '<file1>');

  const options = {method: 'POST', headers: {'Api-Key': '<apiKey>'}};

  options.body = form;

  try {
    const response = await fetch(url, options);
    const data = await response.json();
    console.log(data);
  } catch (error) {
    console.error(error);
  }
  ```

  ```shell Curl theme={null}
  curl -X POST https://aihubmix.com/ideogram/remix \
       -H "Api-Key: <apiKey>" \
       -H "Content-Type: multipart/form-data" \
       -F 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.",
    "aspect_ratio": "ASPECT_10_16",
    "image_weight": 50,
    "magic_prompt_option": "ON",
    "model": "V_2"
  }' \
       -F image_file=@<file1>
  ```
</CodeGroup>

### Response

Image(s) generated successfully.

```json theme={null}
{
  "created": "2000-01-23T04:56:07Z",
  "data": [
    {
      "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's 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.",
      "resolution": "1024x1024",
      "is_image_safe": true,
      "seed": 12345,
      "url": "https://ideogram.ai/api/images/direct/8YEpFzHuS-S6xXEGmCsf7g",
      "style_type": "REALISTIC"
    }
  ]
}
```

### Error Codes

* `400` : Post Remix Image Request Bad Request Error
* `401` : Post Remix Image Request Unauthorized Error
* `422` : Post Remix Image Request Unprocessable Entity Error
* `429` : Post Remix Image Request Too Many Requests Error

### Upscale

`POST` [https://aihubmix.com/ideogram/upscale](https://api.aihubmix.com/ideogram/upscale)

Synchronously upscales the provided image with optional prompts. Supported image formats include JPEG, PNG, and WebP. Image links have a limited validity period; if you want to keep the images, you must download and save them.

**Request Parameters**

<ParamField body="image_request" type="object" required>
  Request object for upscaling the provided image with optional prompts
</ParamField>

<ParamField body="image_request.prompt" type="string">
  Optional prompt to guide the upscaling process
</ParamField>

<ParamField body="image_request.resemblance" default="50" type="integer">
  Resemblance, range: 1-100
</ParamField>

<ParamField body="image_request.detail" default="50" type="integer">
  Detail, range: 1-100
</ParamField>

<ParamField body="image_request.magic_prompt_option" default="AUTO" type="string">
  Prompt enhancement option. Available parameters: AUTO, ON, OFF
</ParamField>

<ParamField body="image_request.num_images" default="1" type="integer">
  Number of images to generate, range: 1-8
</ParamField>

<ParamField body="image_request.seed" type="integer">
  Random seed, range: 0-2147483647
</ParamField>

<ParamField body="image_file" type="file" required>
  Original image file, supports JPEG, PNG, and WebP formats
</ParamField>

### Example Calls

<CodeGroup>
  ```py Python theme={null}
  import requests
  import os

  url = "https://aihubmix.com/ideogram/upscale"

  files = { "image_file": open('<file1>', 'rb') }
  payload = { "image_request": "{}" }
  headers = {"Api-Key": os.getenv("AIHUBMIX_API_KEY")}

  response = requests.post(url, data=payload, files=files, headers=headers)

  print(response.json())
  ```

  ```js Javascript theme={null}
  const url = 'https://aihubmix.com/ideogram/upscale';
  const form = new FormData();
  form.append('image_request', '{}');
  form.append('image_file', '<file1>');

  const options = {method: 'POST', headers: {'Api-Key': '<apiKey>'}};

  options.body = form;

  try {
    const response = await fetch(url, options);
    const data = await response.json();
    console.log(data);
  } catch (error) {
    console.error(error);
  }
  ```

  ```shell Curl theme={null}
  curl -X POST https://aihubmix.com/ideogram/upscale \
       -H "Api-Key: <apiKey>" \
       -H "Content-Type: multipart/form-data" \
       -F image_request='{}' \
       -F image_file=@<file1>
  ```
</CodeGroup>

### Response

Image(s) generated successfully.

```json theme={null}
{
  "created": "2000-01-23T04:56:07Z",
  "data": [
    {
      "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's 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.",
      "resolution": "1024x1024",
      "is_image_safe": true,
      "seed": 12345,
      "url": "https://ideogram.ai/api/images/direct/8YEpFzHuS-S6xXEGmCsf7g",
      "style_type": "REALISTIC"
    }
  ]
}
```

### Error Codes

* `400` : Post Upscale Image Request Bad Request Error
* `401` : Post Upscale Image Request Unauthorized Error
* `422` : Post Upscale Image Request Unprocessable Entity Error
* `429` : Post Upscale Image Request Too Many Requests Error

### Describe

`POST` [https://aihubmix.com/ideogram/describe](https://api.aihubmix.com/ideogram/describe)

Analyzes and describes the uploaded image. Supported image formats include JPEG, PNG, and WebP.

**Request Parameters**

<ParamField body="image_file" type="file" required>
  Image file to describe, supports JPEG, PNG, and WebP formats
</ParamField>

### Example Calls

<CodeGroup>
  ```py Python theme={null}
  import requests
  import os

  url = "https://aihubmix.com/ideogram/describe"

  files = { "image_file": open('<file1>', 'rb') }
  headers = {"Api-Key": os.getenv("AIHUBMIX_API_KEY")}

  response = requests.post(url, files=files, headers=headers)

  print(response.json())

  # close file
  files["image_file"].close()
  ```

  ```js Javascript theme={null}
  const url = 'https://aihubmix.com/ideogram/describe';
  const form = new FormData();
  form.append('image_file', '<file1>');

  const options = {method: 'POST', headers: {'Api-Key': '<apiKey>'}};

  options.body = form;

  try {
    const response = await fetch(url, options);
    const data = await response.json();
    console.log(data);
  } catch (error) {
    console.error(error);
  }
  ```

  ```shell Curl theme={null}
  curl -X POST https://aihubmix.com/ideogram/describe \
       -H "Api-Key: <apiKey>" \
       -H "Content-Type: multipart/form-data" \
       -F image_file=@<file1>
  ```
</CodeGroup>

### Response

Description(s) created successfully.

```json theme={null}
{
  "descriptions": [
    {
      "text": "A meticulously illustrated cat with striped patterns, sitting upright. The cat's eyes are a captivating shade of yellow, and it appears to be gazing intently at something. The background consists of abstract, swirling patterns in shades of black, white, and beige, creating an almost fluid or wavy appearance. The cat is positioned in the foreground, with the background elements fading into the distance, giving a sense of depth to the image."
    },
    {
      "text": "A meticulously illustrated cat with striped patterns, sitting upright. The cat's eyes are a captivating shade of yellow, and it appears to be gazing intently at something. The background consists of abstract, swirling patterns in shades of black, white, and beige, creating an almost fluid or wavy appearance. The cat is positioned in the foreground, with the background elements fading into the distance, giving a sense of depth to the image."
    }
  ]
}
```

### Error Codes

* `400` : Post Describe Request Bad Request Error
* `422` : Post Describe Request Unprocessable Entity Error
* `429` : Post Describe Request Too Many Requests Error

***

### 💰 V2 & V1 Pricing

#### Image Generation

| Model     | Feature                                                                               | Cost per Image |
| --------- | ------------------------------------------------------------------------------------- | -------------- |
| 2a        | Text to image, or text + reference image to image                                     | US \$0.04      |
| 2a Turbo  | Text to image, or text + reference image to image (faster but slightly lower quality) | US \$0.025     |
| 2.0       | Text to image, or text + reference image to image                                     | US \$0.08      |
| 2.0 Turbo | Text to image, or text + reference image to image (faster but slightly lower quality) | US \$0.05      |
| 1.0       | Text to image, or text + reference image to image                                     | US \$0.06      |
| 1.0 Turbo | Text to image, or text + reference image to image (faster but slightly lower quality) | US \$0.02      |

#### Image Editing

| Model          | Feature                                                                                                      | Cost per Image |
| -------------- | ------------------------------------------------------------------------------------------------------------ | -------------- |
| 2.0 Edit       | Regenerate images using text prompts, reference images, and binary masks                                     | US \$0.08      |
| 2.0 Turbo Edit | Regenerate images using text prompts, reference images, and binary masks (faster but slightly lower quality) | US \$0.05      |

#### Image Enhancement

| Model   | Feature                                                                     | Cost per Image |
| ------- | --------------------------------------------------------------------------- | -------------- |
| Upscale | Increase reference image resolution by 2x, possibly enhancing image quality | US \$0.06      |

## For more details, see the [official documentation](https://developer.ideogram.ai/api-reference/api-reference/generate)

Last updated: 2026-06-01