calesthio/generative-media-skills/adobe-firefly-image

Adobe Firefly Image

Treat this as a still-image production and integration skill. Keep video, audio, and unrelated Photoshop, Lightroom, Express, or Creative Production operations out of scope unless the user explicitly asks to combine systems.

Evidence discipline

Use these labels consistently:

• Documented means the current Adobe API reference, changelog, product terms, or security material states the claim.
• Inference means the conclusion follows from documented fields or behavior but Adobe does not state it directly.
• Production heuristic means practical guidance to test in the target account and workflow.

Volatile API facts below were verified on 2026-07-09. Re-check the API reference, changelog, and usage notes immediately before shipping. Adobe has several prose pages whose examples conflict with the endpoint reference. When they disagree, prefer the operation schema in the API reference plus a later explicit changelog entry; do not merge fields from incompatible versions.

Start with the production contract

Before generating anything:

1. Confirm that the organization is entitled to Firefly Services and that the project has OAuth Server-to-Server credentials.
2. Record the deliverable, aspect ratio or dimensions, acceptable alteration of supplied assets, rights/consent status, locale, accessibility needs, and review owner.
3. Choose the operation from the matrix below. Do not select a model only because it is newest.
4. Quote the endpoint, model header, variation count, and cost unit before a paid batch.
5. Run one representative sample, download it immediately, and perform visual and provenance QA before scaling.

Current API and model map

Documented, verified 2026-07-09:

Image 5 is the latest documented image model and exposes 1 MP, 2.4 MP, and 4 MP resolution levels. The v3 model values remain present in the current API schema; do not call them removed merely because Image 5 exists. Adobe removed the deprecated synchronous v3 references on 2025-10-03 and removed Generate Images v2, Expand v1, and Fill v1 on 2025-09-10. Build only against current asynchronous routes. See the changelog.

Resolve documentation conflicts deliberately

Documented conflict, verified 2026-07-09: the Image 5 API reference defines aspectRatio, resolutionLevel, modelId, modelSpecificPayload, and referenceBlobs for /v4/images/generate-async. The Image 5 migration page simultaneously describes some of those fields as removed and presents a payload resembling the v3 custom-model schema. Do not use that migration table as executable schema without reconciling it against the API reference.

Likewise, a prose upscale guide still names /v1/images/upsample-async, while the current API reference and 2026-04-24 changelog identify POST /v3/images/upscale and precise_upsampler_v1. Use the latter. creative_upsampler_v1 is rejected with 422. This is a source-quality decision, not a claim that every Adobe prose page is obsolete.

Authenticate from a server

Documented: Firefly requests require both an Adobe IMS bearer token and the Client ID as x-api-key. Use OAuth Server-to-Server. Never expose the client secret or access token in browser code, logs, prompts, or generated artifacts. Adobe documents 24-hour access-token validity; refresh proactively and retry once after a 401 only after obtaining a fresh token. See Authentication and credentials setup.

Token request:

POST https://ims-na1.adobelogin.com/ims/token/v3
Content-Type: application/x-www-form-urlencoded
 
grant_type=client_credentials&client_id=...&client_secret=...&scope=openid,AdobeID,session,additional_info,read_organizations,firefly_api,ff_apis

Every Firefly API call then includes:

Authorization: Bearer <access-token>
x-api-key: <client-id>
Content-Type: application/json
Accept: application/json

Use the scopes and product profiles actually provisioned in the Developer Console; do not broaden scopes speculatively. A 403 after successful token exchange usually points to entitlement, product-profile, organization, custom-model sharing, policy, or regional access rather than malformed OAuth.

Understand request and response contracts

Image 5: v4 generate and instruct edit

Documented v4 fields:

• prompt: required, 1–1500 characters.
• aspectRatio: 1:1, 4:3, 3:4, 16:9, 9:16, or auto.
• resolutionLevel: 1MP, 2.4MP (default), or 4MP.
• modelId: firefly_image.
• numVariations: maximum 1.
• seeds: maximum one integer; its count must match numVariations when both appear.
• modelSpecificPayload.localeCode: locale control used by Image 5.
• modelSpecificPayload.prompt_reasoner: speed (default) or quality; Adobe says quality populates altText, while speed returns it empty.
• referenceBlobs: maximum one. Empty means text-to-image; non-empty with usage: general means instruct edit. When present, omit aspectRatio or set it to auto.

Do not send v3-only style, structure, contentClass, visualIntensity, or customModelId fields to v4. The v4 operation schema does not document a negative-prompt field or arbitrary output-format selector. Validate the actual response asset Content-Type rather than assuming JPEG or PNG.

The v4 submission returns HTTP 200 with a links.result.href, links.cancel.href, and progress value. It is still asynchronous. Poll the returned result link with the same authorization headers until a terminal state, then download the image URL promptly.

Image 3/4: v3 generate

Documented v3 fields:

• prompt: required, 1–1024 characters.
• negativePrompt: up to 1024 characters; not supported for Image 3 or Image 4 custom models.
• contentClass: photo or art.
• numVariations: 1–4. If seeds are supplied, seed count must equal variation count.
• promptBiasingLocaleCode: BCP-47-like language-region value such as en-US.
• style.presets: documented snake_case presets; combine deliberately.
• style.strength: 1–100, default 50; may accompany a style reference.
• structure.strength: 1–100, default 50; controls outline/depth resemblance to the structure reference.
• visualIntensity: 2–10; not supported by image4_custom.
• upsamplerType: only for image4_custom; default or low_creativity.

Supported generation sizes:

Do not round to a convenient aspect-equivalent size. The service validates exact pairs.

The v3 submission returns HTTP 202 with jobId, statusUrl, and cancelUrl. Poll statusUrl. A running response includes status: running; success includes status: succeeded and result.outputs[], each with a seed and image URL. Treat failed, cancelled, HTTP terminal errors, and a local timeout as terminal outcomes; capture the response body and request ID for support.

Uploads, masks, and source URLs

The upload API accepts binary image data. The current API reference lists PNG, JPEG, WebP, TIFF, and JXL with a 15 MB maximum, while an older upload guide lists only JPEG, PNG, and WebP. Production heuristic: use PNG for masks/transparency and JPEG or PNG for ordinary inputs unless the target account has been tested with the broader formats.

An upload response is shaped as {"images":[{"id":"..."}]}. The API contract says the ID is valid for seven days. Adobe's Firefly Services security sheet separately says uploaded reference content is cached for 24 hours; do not equate cache retention with ID validity.

For v3 source URLs, the operation reference commonly allow-lists amazonaws.com, windows.net, dropboxusercontent.com, and storage.googleapis.com. The Image 5 usage notes add frontdoor.prod.azure.cxp.adobe.com. Requirements vary by operation. Use short-lived HTTPS pre-signed URLs, restrict object permissions, and confirm the exact operation's allow-list. Never pass an arbitrary public URL and assume Firefly will fetch it.

Masks are production assets, not annotations. Inspect dimensions, alpha/gray semantics, inversion, feathering, and alignment before a paid call. expand-async forbids using placement for a source when a mask is also applied. Its output can be up to 3999×3999. Use Fill for a localized masked replacement; use Expand for a larger canvas; use Image 5 instruct edit for a natural-language whole-image refinement where one reference is sufficient.

Choose references and composites by what must remain fixed

Style and structure

Use v3 style.imageReference to transfer visual language such as palette, medium, lighting, or mood. Use structure.imageReference to guide outline and depth. Strength 1–100 changes adherence; default 50. These controls can coexist, but competing high strengths can reduce prompt compliance.