Firefly Custom Models

Firefly Custom Models

Use brand-aligned generative models. Custom Models capture distinctive aesthetics, characters, objects, or compositional patterns from 10-30 reference images and apply them to new generations via customModelId. This is the production pattern for brand-guardrail generative workflows.

Important — training happens in the Firefly web UI, not the API. There is no public REST API for training or deleting custom models — but listing exists: GET /v3/custom-models enumerates the org's models (live-verified 2026-08-10; returns {"custom_models": [...], "total_count": n} with pagination links). Models are trained interactively in the Firefly web app (firefly.adobe.com). Entitlement tip: on a credential whose org has no custom-model access, the API rejects the header outright — 422 Invalid x-model-version: image3_custom. Must be one of: ['image3', 'image3_fast'] — which makes a one-call entitlement check. The Firefly Services API only consumes a trained model at generation time via customModelId plus the x-model-version: image3_custom header. This skill covers preparing data, training in the web UI, finding the model's asset ID, and generating with it.

When to Use This Skill

Use this skill when:

• The user needs brand-consistent output that base Firefly cannot achieve
• A specific subject (mascot, product, character) must appear consistently
• A specific visual style (icon set, illustration style, brand voice) must be enforced
• The user mentions training data, reference images, or fine-tuning
• Iconography, brand assets, or character generation is the use case

Do NOT use this skill when:

• A style preset or style image reference will do the job — start there, only train when those are insufficient
• The customer has not purchased Custom Models entitlement — confirm SKU first
• The reference set is < 10 images or > 1000 — too few yields noise, too many is wasteful

Subject vs Style Models — Pick Correctly

You cannot mix — a model is either subject or style. For a workflow that needs both (specific character in specific style), train two models and use them together via the reference parameters.

The iconography pattern

For enterprise brand iconography, style models (not subject) are the right choice. Train one style model per distinct icon treatment your brand uses — typical sets include light, dark, and functional variants. Each model is trained on 10-30 examples that share the visual treatment. Workflow:

1. User prompt: "an icon of a key"
2. Generate with the appropriate style custom model
3. Output is in the brand icon style automatically — no human styling needed
4. Last-mile edit in Adobe Express if needed

Result: icon production cycle time can be reduced dramatically — from days or weeks of design work down to a single review-and-polish session.

Step 1 — Prepare Training Data

Quality of training data is the dominant factor in output quality. The single biggest mistake is uploading bad data.

Subject models

10-30 images of the same subject from varied angles, lighting, and contexts. The model needs to learn what is consistent about the subject — uniform images teach nothing about variation.

Style models

10-30 images that share the visual style you want to capture. They should NOT all be the same subject — different subjects rendered in the same style is what teaches the model to apply the style independent of content.

Quality checklist

Filter aggressively. A 15-image set of strong examples beats a 30-image set with 5 weak ones.

Step 2 — Train the Model in the Firefly Web App

Custom Models are trained interactively in the Firefly web app (firefly.adobe.com) by a user with a Custom Models entitlement — not via a REST call. The workflow:

1. In the Firefly web app, start a new custom model and choose Subject or Style.
2. Upload the curated 10-30 reference images prepared in Step 1.
3. Add a short caption to each image describing what it depicts. Captions matter — they teach the model what each image is depicting, and training quality drops significantly without them.
4. Name the model using a consistent convention (see below) and start training.
5. Training runs server-side and can take a while (often an hour or more, depending on dataset size and queue depth). The web app shows progress; you do not poll an API.

Naming convention

Names appear in the web app, audit trails, and downstream dashboards. Good names save weeks of "which model was that?".

Step 3 — Find the Model's Asset ID

When training completes, the model exists as an asset in your Firefly account. Open the model in the Firefly web app and copy its asset ID (assetId). That asset ID is exactly the value you pass as customModelId in generation requests — they are the same identifier. Record it in your model registry alongside the model name and version.

Step 4 — Generate With the Custom Model

Generate with the model by passing its asset ID as customModelId and sending the x-model-version: image3_custom header:

curl --silent -X POST 'https://firefly-api.adobe.io/v3/images/generate' \
  -H "Authorization: Bearer $FIREFLY_SERVICES_ACCESS_TOKEN" \
  -H "X-Api-Key: $FIREFLY_SERVICES_CLIENT_ID" \
  -H 'x-model-version: image3_custom' \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "an icon of a key",
    "customModelId": "00000000-0000-0000-0000-000000000000",
    "contentClass": "art",
    "size": {"width": 1024, "height": 1024}
  }'

The x-model-version: image3_custom header is required — without it, the request runs against the base Firefly model and ignores customModelId. This is the #1 silent failure mode in custom-model workflows.

Step 5 — Manage Models

Retraining and deleting custom models is done in the Firefly web app; enumerate them programmatically with GET /v3/custom-models (live-verified). Still maintain your own registry mapping model name → asset ID (customModelId) → version so generation services can look up the right ID. Treat asset IDs as long-lived; deleting a model in the web app cannot be undone, so confirm before removing one that is in production.

Step 6 — Retraining Cadence

Models capture a moment-in-time of brand aesthetics. When the brand evolves, the model must too.

Version models explicitly: <name>-v2, <name>-v3. Maintain a registry of which version is in production. The registry can live in your own configuration or asset-management system.

Production Patterns

Pattern: Per-customer model library

Multi-customer FDE deployments maintain a separate model library per customer. Models are not shared across customers — both for IP-protection reasons and because brand styles do not transfer.

Each customer's model IDs are stored in their config (or in a per-account profile). The serving layer looks up the right ID per-request.

Pattern: Style + structure with custom model

Custom models combine with reference images:

{
  "prompt": "an icon of a key",
  "customModelId": "brand-light-icon-style-id",
  "structure": {
    "imageReference": {"source": {"uploadId": "abc-123"}},
    "strength": 60
  }
}

The custom model dictates style; the structure reference dictates composition. Powerful for icon generation where consistent style + specific shape is needed.

Validate

A custom-model workflow is production-ready when:

1. Training data is curated (10-30 high-quality examples, captioned)
2. Trained models are tracked by customModelId (asset ID) in a model registry
3. Generation calls include x-model-version: image3_custom (this is the silent failure)
4. Output samples are reviewed against brand guidelines before generation goes live
5. A retraining cadence is documented (typically quarterly or on brand updates)
6. Model IDs are stored in customer-specific config, not hardcoded

Troubleshooting & Edge Cases

• x-model-version header missing: Generation silently uses the base model. Custom output looks generic. Add the header.
• Training fails or is rejected in the web app: Almost always bad training data — too few images, low resolution, or inconsistent style. Re-curate and retrain.
• Output looks nothing like the training data: Training set was too uniform (subject model) or too varied (style model). Audit and re-curate.
• Generation rate-limited: Custom-model generation shares Firefly generation quota. See firefly-services-rate-limits.
• customModelId returns 404: Confirm the credential's IMS org matches the org that trained the model. Custom models are scoped to the training org. Also confirm the asset ID was copied correctly.
• Output quality degraded after Adobe model update: The base model under the custom layer was updated. Retrain to align with the new base.

Chaining with Other Skills

• firefly-services-storage-refs — Storage references for reference images used at generation time
• firefly-generate-image-v3-async — Generation pipeline
• firefly-services-troubleshoot — When generation fails

References

• Firefly Custom Models Overview
• Custom Models — Generate Image guide
• Custom Models — Share Model guide