AiHubMix Documentation Hub

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 Gere

POST https://aihubmix.com/ideogram/v1/ideogram-v3/generate Gere images based on given prompts. The V3 model provides higher quality image generation capabilities, supporting more diverse styles and parameter controls.

prompt

string

obrigatório

Prompt for image generation

rendering_speed

string

padrão:"DEFAULT"

Rendering speed options, available TURBO, DEFAULT, QUALITY

num_images

integer

padrão:"1"

Number of images to generate, range 1-8
Gerando more images will not significantly increase the generation time

aspect_ratio

string

padrão:"1x1"

Aspect ratio for image generation, suporta 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.

magic_prompt

string

padrão:"AUTO"

Prompt enhancement. Available parameters: AUTO, ON, OFF

style_type

string

padrão:"AUTO"

Style type for image generation, available AUTO, GENERAL, REALISTIC, DESIGN
Note: Compared to V2 version, the type is more focused

negative_prompt

string

Description of content you do not want to appear no image

seed

integer

Random seed, range: 0-2147483647
Do not use seed when generating multiple images, otherwise the same image will be generated

style_reference_images

file

Style reference image, can be used for style guidance

Usage Examples

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"

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

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

V3 Remix

POST 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.

prompt

string

obrigatório

Prompt for image remixing

image

file

obrigatório

Original image file

image_weight

integer

padrão:"50"

The weight of the original image, range 1-100, the larger the value, the more similar the result to the original image.

rendering_speed

string

padrão:"DEFAULT"

Rendering speed options, available TURBO, DEFAULT, QUALITY

num_images

integer

padrão:"1"

Number of images to generate, range 1-8 Gerando more images will not significantly increase the generation time

aspect_ratio

string

Aspect ratio of the output image, available [‘1x3’, ‘3x1’, ‘1x2’, ‘2x1’, ‘9x16’, ‘16x9’, ‘10x16’, ‘16x10’, ‘2x3’, ‘3x2’, ‘3x4’, ‘4x3’, ‘4x5’, ‘5x4’, ‘1x1’]

style_reference_images

file

Style reference image, can be used for style guidance

seed

integer

Random seed, range: 0-2147483647

magic_prompt

string

padrão:"AUTO"

Prompt enhancement. Available parameters: AUTO, ON, OFF

style_type

string

padrão:"AUTO"

Style type for image generation, available AUTO, GENERAL, REALISTIC, DESIGN

negative_prompt

string

Description of content you do not want to appear no image

Usage Examples

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

V3 Edit

POST 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.

prompt

string

obrigatório

Prompt for image editing

image

file

obrigatório

Original image file

mask

file

obrigatório

Mask image, black area represents the part to be edited, white area represents the part to be kept unchanged

rendering_speed

string

padrão:"DEFAULT"

Rendering speed options, available TURBO, DEFAULT, QUALITY

num_images

integer

padrão:"1"

Number of images to generate, range 1-8 Gerando more images will not significantly increase the generation time

aspect_ratio

string

seed

integer

Random seed, range: 0-2147483647

magic_prompt

string

padrão:"AUTO"

Prompt enhancement. Available parameters: AUTO, ON, OFF

style_type

string

padrão:"AUTO"

Style type for image generation, available AUTO, GENERAL, REALISTIC, DESIGN

negative_prompt

string

Description of content you do not want to appear no image

Usage Examples

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

V3 Replace Background

POST https://aihubmix.com/ideogram/v1/ideogram-v3/replace-background V3 的背景替换功能可以智能地识别图像的前景和背景，并根据提示词替换背景，同时保持前景对象不变。

prompt

string

obrigatório

Prompt for background replacement

image

file

obrigatório

Original image file

rendering_speed

string

padrão:"DEFAULT"

Rendering speed options, available TURBO, DEFAULT, QUALITY

num_images

integer

padrão:"1"

Number of images to generate, range 1-8 Gerando more images will not significantly increase the generation time

style_reference_images

file

Style reference image, can be used for style guidance

seed

integer

Random seed, range: 0-2147483647

magic_prompt

string

padrão:"AUTO"

Prompt enhancement. Available parameters: AUTO, ON, OFF

style_type

string

padrão:"AUTO"

Style type for image generation, available AUTO, GENERAL, REALISTIC, DESIGN

Usage Examples

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

For more optional parameters, consulte Ideogram AI

💰 V3 Pricing

Ideogram v3	Gere	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

Available through the official AiHubMix API or Cherry Studio APP. Note que currently a proxy é obrigatório for image generation; direct connection within China will be supported no future.
Cherry Studio currently only offers the Ideogram drawing (generate) interface.

Gere

POST https://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 salve om. Request Parameters

image_request

object

obrigatório

Request object for image generation

image_request.prompt

string

obrigatório

Prompt for image generation

image_request.aspect_ratio

string

padrão:"ASPECT_1_1"

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

image_request.model

string

padrão:"V_2"

Model for generating or editing images. /generate and /remix support all model types, but /edit only suporta V_2 and V_2_TURBO.Available model versions:

V_1
V_1_TURBO
V_2
V_2_TURBO
V_2A
V_2A_TURBO

image_request.magic_prompt_option

string

padrão:"AUTO"

Prompt enhancement option. Available parameters: AUTO, ON, OFF

image_request.seed

integer

Random seed, range: 0-2147483647

image_request.style_type

string

padrão:"AUTO"

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

image_request.negative_prompt

string

Describes what you don’t want to appear no image. Only applicable to model versions V_1, V_1_TURBO, V_2, and V_2_TURBO. Descriptions no prompt take precedence over descriptions no negative prompt.

image_request.num_images

integer

padrão:"1"

Number of images to generate, range 1-8

image_request.resolution

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.

Example Calls

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())

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

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

Response

Image(s) generated com sucesso.

{
  "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 Gere Image Request Bad Request Error
401 : Post Gere Image Request Unauthorized Error
422 : Post Gere Image Request Unprocessable Entity Error
429 : Post Gere Image Request Too Many Requests Error

Edit

POST https://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 salve om. Request Parameters

image_file

file

obrigatório

Original image file, suporta JPEG, PNG, and WebP formats

mask

file

obrigatório

Mask image, must meet o seguinte requirements:

Contains only black and white pixels, suporta 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

prompt

string

obrigatório

Prompt for local editing

model

string

obrigatório

Model for generating or editing images. /generate and /remix support all model types, but /edit only suporta V_2 and V_2_TURBO.Available model versions:

V_2
V_2_TURBO

magic_prompt_option

string

padrão:"AUTO"

Prompt enhancement option. Available parameters: AUTO, ON, OFF

num_images

integer

padrão:"1"

Number of images to generate, range 1-8

seed

integer

Random seed, range: 0-2147483647

style_type

string

padrão:"AUTO"

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

Example Calls

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()

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

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"

Response

Image edits generated com sucesso.

{
  "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 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 salve om. Request Parameters

image_request

object

obrigatório

Request to generate new images using the provided image and prompt. The provided image will be cropped to match the selected output aspect ratio.

image_request.prompt

string

obrigatório

Prompt for image generation

image_request.aspect_ratio

string

padrão:"ASPECT_1_1"

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

image_request.image_weight

integer

padrão:"50"

Reference image weight, range: 1-100

image_request.model

string

padrão:"V_2"

Model for generating or editing images. /generate and /remix support all model types, but /edit only suporta V_2 and V_2_TURBO.

image_request.negative_prompt

string

Describes what you don’t want to appear no image. Only applicable to model versions V_1, V_1_TURBO, V_2, and V_2_TURBO. Descriptions no prompt take precedence over descriptions no negative prompt.

image_request.magic_prompt_option

string

padrão:"AUTO"

Prompt enhancement option. Available parameters: AUTO, ON, OFF

image_request.num_images

integer

padrão:"1"

Number of images to generate, range: 1-8

image_request.resolution

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.

image_request.seed

integer

Random seed, range: 0-2147483647

image_request.style_type

string

padrão:"AUTO"

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

image_file

file

obrigatório

Original image file, suporta JPEG, PNG, and WebP formats

Example Calls

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())

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

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>

Response

Image(s) generated com sucesso.

{
  "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 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 salve om. Request Parameters

image_request

object

obrigatório

Request object for upscaling the provided image with optional prompts

image_request.prompt

string

Optional prompt to guide the upscaling process

image_request.resemblance

integer

padrão:"50"

Resemblance, range: 1-100

image_request.detail

integer

padrão:"50"

Detail, range: 1-100

image_request.magic_prompt_option

string

padrão:"AUTO"

Prompt enhancement option. Available parameters: AUTO, ON, OFF

image_request.num_images

integer

padrão:"1"

Number of images to generate, range: 1-8

image_request.seed

integer

Random seed, range: 0-2147483647

image_file

file

obrigatório

Original image file, suporta JPEG, PNG, and WebP formats

Example Calls

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())

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

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>

Response

Image(s) generated com sucesso.

{
  "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 Analyzes and describes the uploaded image. Supported image formats include JPEG, PNG, and WebP. Request Parameters

image_file

file

obrigatório

Image file to describe, suporta JPEG, PNG, and WebP formats

Example Calls

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()

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

curl -X POST https://aihubmix.com/ideogram/describe \
     -H "Api-Key: <apiKey>" \
     -H "Content-Type: multipart/form-data" \
     -F image_file=@<file1>

Response

Description(s) created com sucesso.

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

Para mais detalhes, see the official documentation

Última atualização: 2026-06-01

​Ideogram V3 Interface

​V3 Gere

​Usage Examples

​V3 Remix

​Usage Examples

​V3 Edit

​Usage Examples

​V3 Replace Background

​Usage Examples

​💰 V3 Pricing

​V2 & V1 Interface Description

​Gere

​Example Calls

​Response

​Error Codes

​Edit

​Example Calls

​Response

​Error Codes

​Remix

​Example Calls

​Response

​Error Codes

​Upscale

​Example Calls

​Response

​Error Codes

​Describe

​Example Calls

​Response

​Error Codes

​💰 V2 & V1 Pricing

​Image Generation

​Image Editing

​Image Enhancement

​Para mais detalhes, see the official documentation

Ideogram V3 Interface

V3 Gere

Usage Examples

V3 Remix

Usage Examples

V3 Edit

Usage Examples

V3 Replace Background

Usage Examples

💰 V3 Pricing

V2 & V1 Interface Description

Gere

Example Calls

Response

Error Codes

Edit

Example Calls

Response

Error Codes

Remix

Example Calls

Response

Error Codes

Upscale

Example Calls

Response

Error Codes

Describe

Example Calls

Response

Error Codes

💰 V2 & V1 Pricing

Image Generation

Image Editing

Image Enhancement

Para mais detalhes, see the official documentation