Overview
Custom model training lets you fine-tune an Ideogram model on your own dataset of images via the API. Once training completes, you can generate images using your trained model by passing its custom_model_uri to the Generate endpoint.
1
Create a dataset
→
2
Upload images
→
3
Train model
4
Check status
→
5
Generate
Endpoint reference
| Endpoint | Method | Description |
|---|---|---|
/datasets |
GET | List all datasets for the authenticated user |
/datasets |
POST | Create a new dataset |
/datasets/{dataset_id}/upload_assets |
POST | Upload images and captions to a dataset |
/datasets/{dataset_id}/train_model |
POST | Start training a model from a dataset |
/models |
GET | List custom models (owned or shared) |
/models/{model_id} |
GET | Get details for a specific model |
Step 1: Create a dataset
import requests
response = requests.post(
"https://api.ideogram.ai/datasets",
headers={"Api-Key": "<apiKey>"},
json={"name": "My Training Dataset"}
)
dataset = response.json()
dataset_id = dataset["dataset_id"]
print(f"Created dataset: {dataset_id}")Step 2: Upload training images
Upload images (JPEG, PNG, WebP), optional .txt caption sidecar files, or ZIP archives containing both.
Minimum: 10 images per dataset
Maximum: 100 images per dataset
Captions: Matched by filename stem (e.g.
sunset.txt captions sunset.jpg)Tip: Upload a ZIP file for larger datasets. If images are very large, upload in batches to avoid timeouts.
import requests
import glob
files = [("files", open(f, "rb")) for f in glob.glob("training_images/*.jpg")]
response = requests.post(
f"https://api.ideogram.ai/datasets/{dataset_id}/upload_assets",
headers={"Api-Key": "<apiKey>"},
files=files
)
result = response.json()
print(f"Uploaded {result['success_count']}/{result['total_count']} images")Step 3: Train the model
Once your dataset has enough images, start training by giving your model a name.
response = requests.post(
f"https://api.ideogram.ai/datasets/{dataset_id}/train_model",
headers={"Api-Key": "<apiKey>"},
json={"model_name": "my-custom-model"}
)
training = response.json()
model_id = training["model_id"]
print(f"Training started: {training['training_status']}")Step 4: Check training status
Poll the model details endpoint to check when training completes.
CREATING
→
DRAFT
→
TRAINING
→
COMPLETED
import time
while True:
response = requests.get(
f"https://api.ideogram.ai/models/{model_id}",
headers={"Api-Key": "<apiKey>"}
)
model = response.json()["model"]
print(f"Status: {model['status']}")
if model["status"] == "COMPLETED":
print(f"Model ready! URI: {model.get('custom_model_uri')}")
break
elif model["status"] == "ERRORED":
print("Training failed.")
break
time.sleep(60)Step 5: Generate with your model
Once training is complete and is_available_for_generation is true, use the custom_model_uri from the model details to generate images.
response = requests.post(
"https://api.ideogram.ai/v1/ideogram-v3/generate",
headers={"Api-Key": "<apiKey>"},
data={
"prompt": "A photo in my custom style",
"custom_model_uri": "model/my-custom-model/version/1",
"rendering_speed": "DEFAULT"
}
)
result = response.json()
if response.status_code == 200:
print(result["data"][0]["url"])Tips for better results
- Use high-quality images that clearly represent the style or subject you want the model to learn.
- Add captions to guide the model on what each image represents. Captions are optional but improve alignment.
- Use consistent subjects across your training images for best results with style transfer.