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.