Firefly Generate Similar

Firefly Generate Similar

Generate variations of a source image. This is the workhorse API for campaign asset multiplication — one approved hero becomes 10, 50, or 200 variations for A/B testing, channel adaptation, and creative iteration.

When to Use This Skill

Use this skill when:

• The user has an approved source image and wants variations of it
• A campaign needs many derivatives from a single hero asset
• A/B testing requires multiple options from the same concept
• The user mentions "variations", "more like this", "similar but different"

Do NOT use this skill when:

• The user wants a completely new image — use firefly-generate-image-v3-async
• The user wants to extend the canvas — use firefly-expand-fill
• The user wants the same image with a different background — use firefly-expand-fill (Fill)
• The variations need to match a style learned from many images — use firefly-custom-models

Generate Similar vs Generate with Style Reference

A subtle but important distinction:

Generate Similar treats the source as an anchor — outputs are recognizable derivatives. Style reference treats the source as inspiration — outputs share aesthetic but not subject.

For campaign variation generation (hero-asset variants for a single approved concept), Generate Similar is correct. For applying brand style to new subjects across a campaign creator, use Generate Image with style.imageReference — see firefly-generate-image-v3-async.

Step 1 — Submit the Generate Similar Job

curl --silent -X POST 'https://firefly-api.adobe.io/v3/images/generate-similar' \
  -H "Authorization: Bearer $FIREFLY_SERVICES_ACCESS_TOKEN" \
  -H "X-Api-Key: $FIREFLY_SERVICES_CLIENT_ID" \
  -H 'Content-Type: application/json' \
  -d "{
    \"image\": {\"source\": {\"uploadId\": \"$SOURCE_UPLOAD_ID\"}},
    \"numVariations\": 4,
    \"size\": {\"width\": 1024, \"height\": 1024}
  }"

Returns synchronously — the 200 response body contains size and outputs[] with pre-signed result URLs. No polling required.

Step 2 — Request Shape

{
  "image": {"source": {"uploadId": "abc-123"}},
  "numVariations": 4,
  "size": {"width": 1024, "height": 1024},
  "seeds": [12345, 67890, 11111, 22222]
}

Step 3 — Controlling Variation Diversity

Generate Similar's diversity is implicit — the API decides how far to deviate from the source. There is no strength parameter, unlike style reference.

To get more diversity, run multiple jobs with different seeds. The variation between jobs is larger than the variation within a job.

To get less diversity (keep variations very close to source), generate fewer variations per job (1-2) — Firefly tends to make stronger deviations in larger variation sets.

Step 4 — The Variation Pipeline Pattern

For a typical "50 variations of one hero asset" workload:

async function generateNVariations({ sourceUploadId, n }) {
  const variationsPerJob = 4;
  const numJobs = Math.ceil(n / variationsPerJob);

  const jobPromises = Array.from({ length: numJobs }, (_, i) =>
    submitGenerateSimilar({
      sourceUploadId,
      numVariations: variationsPerJob,
      seeds: [
        Math.floor(Math.random() * 1_000_000),
        Math.floor(Math.random() * 1_000_000),
        Math.floor(Math.random() * 1_000_000),
        Math.floor(Math.random() * 1_000_000),
      ],
    }),
  );

  const results = await Promise.all(jobPromises);
  return results.flatMap(r => r.result.outputs);
}

Each job runs in parallel (limited by token-bucket — see firefly-services-rate-limits). 50 variations = 13 parallel jobs. With a provisioned higher RPM (typical for enterprise contracts), this completes in roughly 30 seconds end-to-end.

Production Patterns

Pattern: Hero → variation funnel

Approved hero asset (uploaded to your bucket once)
  ↓ Generate Similar × N (each job 2-4 variations)
50 candidate variations
  ↓ Human selection (or automated quality scoring)
Top 10 chosen
  ↓ Auto-resize via Expand (multiple aspect ratios)
40 final assets (10 variations × 4 aspects)

This is the multiplication pattern that turns a manual "create N variants" effort (weeks of designer work) into a "submit one source, pick the best ten" workflow (hours of work).

Pattern: A/B with pinned seeds

For experiments where outputs need to be traceable and consistent:

const seeds = await db.assignSeedsForExperiment(experimentId);
// Same experiment + same seeds biases toward consistent compositions
const variations = await submitGenerateSimilar({
  sourceUploadId: HERO_ID,
  numVariations: seeds.length,
  seeds,
});

Store seeds with the experiment record and archive the output assets themselves. Seeds bias generation toward a consistent composition, but they do not guarantee byte-identical reproduction — a live check (2026-08-10) comparing calls with identical inputs and seeds returned different image bytes. The seed documents provenance; the archived asset is the reproducibility record.

Validate

A Generate Similar pipeline is production-ready when:

1. Source assets are uploaded once and reused across many variation jobs (don't re-upload per job)
2. Variation count is appropriate to the use case (3-4 per job, multiple jobs for more)
3. Seeds are explicitly set and recorded when consistency matters — and output assets are archived, since seeds bias composition but do not guarantee byte-identical regeneration
4. Output URLs are downloaded immediately and re-hosted in your own bucket
5. Variation jobs run in parallel within rate limits, not serially

Troubleshooting & Edge Cases

• All variations look nearly identical: Seeds are the same, which biases every output toward the same composition. Randomize seeds across the job.
• Variations are too far from the source: Submit smaller variation batches (1-2 per job). Larger batches push more diversity.
• Output is the same as the source: Source is being read but the model decided minimum deviation was appropriate. Try a different source — heavily-processed or composited photos give the model less to work with, and it may return minimal deviation.
• Aspect ratio of output differs from source: Set size explicitly. The default is 2048×2048 (square) regardless of the source's aspect ratio.
• Source image returns 400312: Storage reference is stale or expired. See firefly-services-storage-refs.

Chaining with Other Skills

• firefly-services-storage-refs — Source asset upload
• firefly-generate-image-v3-async — New-image generation (Generate Similar itself returns synchronously)
• firefly-expand-fill — Aspect-ratio expansion of selected variations
• firefly-services-rate-limits — Batch parallelism

References

• Generate Similar API Reference
• Image Upload Concept
• Seeds Concept