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.
POSThttps://aihubmix.com/ideogram/v1/ideogram-v3/generateGenerate images based on given prompts. The V3 model provides higher quality image generation capabilities, supporting more diverse styles and parameter controls.
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.
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 requestsimport osdata = { "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 - requiredsource_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 parameterfiles = None# Style reference image pathstyle_reference_path = "yourpath/reference-image.png"use_reference_image = True# Prepare the files for uploadwith 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 fileresponse_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}")
POSThttps://aihubmix.com/ideogram/v1/ideogram-v3/editThe 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.
import requestsimport osdata = { "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 - requiredsource_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 parameterfiles = None# Style reference image pathstyle_reference_path = "yourpath/reference-image.png"use_reference_image = True# Prepare fileswith 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 fileresponse_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, please refer to Ideogram AI
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 that currently a proxy is required for image generation; direct connection within China will be supported in the future.
Cherry Studio currently only offers the Ideogram drawing (generate) interface.
POSThttps://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
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:
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:
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.
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.
import requestsimport osurl = "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())
{ "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" } ]}
POSThttps://aihubmix.com/ideogram/editSynchronously 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
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:
{ "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" } ]}
POSThttps://aihubmix.com/ideogram/remixFuses 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
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.
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.
{ "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" } ]}
POSThttps://aihubmix.com/ideogram/upscaleSynchronously 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
{ "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" } ]}
POSThttps://aihubmix.com/ideogram/describeAnalyzes and describes the uploaded image. Supported image formats include JPEG, PNG, and WebP.Request Parameters
{ "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." } ]}