@fias/create-fias-plugin 1.15.0 → 1.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fias/create-fias-plugin",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "publishConfig": {
     "access": "public"
   },

package/templates/default/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- fias-sdk-guide-version: 2.23.0 -->
+<!-- fias-sdk-guide-version: 2.24.0 -->
 
 # FIAS Plugin Development Guide
 
@@ -551,6 +551,8 @@ function ModelPicker({ value, onChange }: { value: string; onChange: (id: string
 
 Generate images using platform image models. Images are saved to the user's Fias file system and a display URL is returned.
 
+Most images take 10–60 seconds; high quality at large sizes (the GPT Image models especially) can take several minutes, so `generate` waits up to 320 seconds before rejecting. Show progress for the whole wait (`estimatedDurationMs` from `useImageEntities` sizes it), and do not race `generate` against a shorter timeout of your own — the platform is still rendering, and bills, an image your plugin stopped waiting for.
+
 #### Choosing an image model
 
 The `entityId` parameter accepts three forms. **Prefer the selector forms** (`platformRecommended` / `providerRecommended`) over hardcoded entity IDs: the platform's recommendations evolve, models get retired, and a selector lets your plugin pick up the current best automatically without a code edit. Hardcoded IDs are still supported for back-compat and for cases where you want a specific model — but if the platform retires that exact entity, your plugin breaks unless the platform has registered a successor.
@@ -583,7 +585,7 @@ generate({
 
 Mode values: `'text-to-image'` (baseline), `'image-to-image'` (requires `referenceImage`), `'vector'` (SVG output). Style values: `'illustration'` (stylized / digital-art) or `'photoreal'`.
 
-**Several reference images, and output resolution.** A model whose `maxReferenceImages` (from `useImageEntities`) is more than one takes them together in `referenceImages` — Nano Banana 2 (`ent_modeldef_nano_banana_2`) takes up to 14. There is no role per image: the model reads them in order, so the prompt says which is which. `resolution` picks one of the model's `supportedResolutions`; higher costs more (`creditsPerImageByResolution`):
+**Several reference images, and output resolution.** A model whose `maxReferenceImages` (from `useImageEntities`) is more than one takes them together in `referenceImages` — Nano Banana 2 (`ent_modeldef_nano_banana_2`) takes up to 14, the GPT Image models up to 16. There is no role per image: the model reads them in order, so the prompt says which is which. `resolution` picks one of the model's `supportedResolutions`; higher costs more (`creditsPerImageByResolution`):
 
 ```tsx
 generate({
@@ -670,13 +672,14 @@ const { entities, isLoading } = useImageEntities({
 // entities[i]: { entityId, displayName, provider, modes, supportedSizes,
 //                supportsReferenceImage, maxReferenceImages,
 //                supportedResolutions, defaultResolution, isPlatformRecommended,
-//                creditsPerImage, creditsPerImageByResolution,
+//                pricedBy, pixelSizes, defaultQuality,
+//                creditsPerImage, creditsPerImageByResolution, creditsPerImageByTier,
 //                estimatedDurationMs, company, strengths, providerParams, ... }
 ```
 
 Each entry is scrubbed — only fields a UI legitimately needs (no provider model strings, no endpoints, no execution config).
 
-`creditsPerImage` is what one image costs the user in credits, markup already included — it matches what the ledger deducts, so it is the figure to show. For a model priced by resolution it is the price at `defaultResolution`, and `creditsPerImageByResolution` has each resolution's; Nano Banana 2 also bills reference images and thinking as tokens on top (a fraction of a credit to a few credits). `estimatedDurationMs` sizes a progress indicator; `company` and `strengths` are model-info copy. All optional: absent means the model has nothing to declare, not that the data is missing.
+`creditsPerImage` is what one image costs the user in credits, markup already included — it matches what the ledger deducts, so it is the figure to show. For a model priced by resolution it is the price at `defaultResolution`, and `creditsPerImageByResolution` has each resolution's; Nano Banana 2 also bills reference images and thinking as tokens on top (a fraction of a credit to a few credits). The GPT Image models are `pricedBy: 'quality-and-size'`: `creditsPerImage` is the price at `defaultQuality`, the first `supportedSizes` entry and `defaultResolution`, and `creditsPerImageByTier` has every other, keyed `'<quality>@<WIDTHxHEIGHT>'` — find the pixel size in `pixelSizes` (`'16:9/2K'` → `'2048x1152'`), so a request's price is `creditsPerImageByTier[quality + '@' + pixelSizes[size + '/' + resolution]]`. Their prompt and reference images are billed as tokens on top. `estimatedDurationMs` sizes a progress indicator; `company` and `strengths` are model-info copy. All optional: absent means the model has nothing to declare, not that the data is missing.
 
 **Tunable engine parameters.** `providerParams` describes what a model exposes for tuning — enough to render a settings panel without hardcoding a thing:
 
@@ -688,7 +691,7 @@ const seed = entity.providerParams?.find((p) => p.key === 'seed');
 await generate({ entityId, prompt, providerParams: { seed: 42 } });
 ```
 
-Nano Banana 2 exposes `seed`, `temperature` (0–2) and `thinking_level` (`'minimal'` default, or `'high'` — the model plans the picture first: better at layouts and directions like "seen from above", slower, and its thinking tokens are billed).
+Nano Banana 2 exposes `seed`, `temperature` (0–2) and `thinking_level` (`'minimal'` default, or `'high'` — the model plans the picture first: better at layouts and directions like "seen from above", slower, and its thinking tokens are billed). The GPT Image models expose `output_format` (`'png'` default, `'jpeg'`, `'webp'`) and `output_compression` (0–100, JPEG and WebP only); GPT Image 1.5 and the GPT Image 2.5 models also take `background` (`'auto'`, `'opaque'`, `'transparent'` — transparent needs PNG or WebP).
 
 **The `category` trap.** A param carrying `category: 'quality'` or `'style'` does NOT belong in `providerParams` — send it on the matching top-level field. Providers read those two from the top level only, and an unrecognized `providerParams` key is dropped without an error, so the image generates at the model's default **and you are billed for it anyway**:
 

package/templates/default/CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- fias-sdk-guide-version: 2.23.0 -->
+<!-- fias-sdk-guide-version: 2.24.0 -->
 
 # FIAS Plugin Development Guide
 
@@ -551,6 +551,8 @@ function ModelPicker({ value, onChange }: { value: string; onChange: (id: string
 
 Generate images using platform image models. Images are saved to the user's Fias file system and a display URL is returned.
 
+Most images take 10–60 seconds; high quality at large sizes (the GPT Image models especially) can take several minutes, so `generate` waits up to 320 seconds before rejecting. Show progress for the whole wait (`estimatedDurationMs` from `useImageEntities` sizes it), and do not race `generate` against a shorter timeout of your own — the platform is still rendering, and bills, an image your plugin stopped waiting for.
+
 #### Choosing an image model
 
 The `entityId` parameter accepts three forms. **Prefer the selector forms** (`platformRecommended` / `providerRecommended`) over hardcoded entity IDs: the platform's recommendations evolve, models get retired, and a selector lets your plugin pick up the current best automatically without a code edit. Hardcoded IDs are still supported for back-compat and for cases where you want a specific model — but if the platform retires that exact entity, your plugin breaks unless the platform has registered a successor.
@@ -583,7 +585,7 @@ generate({
 
 Mode values: `'text-to-image'` (baseline), `'image-to-image'` (requires `referenceImage`), `'vector'` (SVG output). Style values: `'illustration'` (stylized / digital-art) or `'photoreal'`.
 
-**Several reference images, and output resolution.** A model whose `maxReferenceImages` (from `useImageEntities`) is more than one takes them together in `referenceImages` — Nano Banana 2 (`ent_modeldef_nano_banana_2`) takes up to 14. There is no role per image: the model reads them in order, so the prompt says which is which. `resolution` picks one of the model's `supportedResolutions`; higher costs more (`creditsPerImageByResolution`):
+**Several reference images, and output resolution.** A model whose `maxReferenceImages` (from `useImageEntities`) is more than one takes them together in `referenceImages` — Nano Banana 2 (`ent_modeldef_nano_banana_2`) takes up to 14, the GPT Image models up to 16. There is no role per image: the model reads them in order, so the prompt says which is which. `resolution` picks one of the model's `supportedResolutions`; higher costs more (`creditsPerImageByResolution`):
 
 ```tsx
 generate({
@@ -670,13 +672,14 @@ const { entities, isLoading } = useImageEntities({
 // entities[i]: { entityId, displayName, provider, modes, supportedSizes,
 //                supportsReferenceImage, maxReferenceImages,
 //                supportedResolutions, defaultResolution, isPlatformRecommended,
-//                creditsPerImage, creditsPerImageByResolution,
+//                pricedBy, pixelSizes, defaultQuality,
+//                creditsPerImage, creditsPerImageByResolution, creditsPerImageByTier,
 //                estimatedDurationMs, company, strengths, providerParams, ... }
 ```
 
 Each entry is scrubbed — only fields a UI legitimately needs (no provider model strings, no endpoints, no execution config).
 
-`creditsPerImage` is what one image costs the user in credits, markup already included — it matches what the ledger deducts, so it is the figure to show. For a model priced by resolution it is the price at `defaultResolution`, and `creditsPerImageByResolution` has each resolution's; Nano Banana 2 also bills reference images and thinking as tokens on top (a fraction of a credit to a few credits). `estimatedDurationMs` sizes a progress indicator; `company` and `strengths` are model-info copy. All optional: absent means the model has nothing to declare, not that the data is missing.
+`creditsPerImage` is what one image costs the user in credits, markup already included — it matches what the ledger deducts, so it is the figure to show. For a model priced by resolution it is the price at `defaultResolution`, and `creditsPerImageByResolution` has each resolution's; Nano Banana 2 also bills reference images and thinking as tokens on top (a fraction of a credit to a few credits). The GPT Image models are `pricedBy: 'quality-and-size'`: `creditsPerImage` is the price at `defaultQuality`, the first `supportedSizes` entry and `defaultResolution`, and `creditsPerImageByTier` has every other, keyed `'<quality>@<WIDTHxHEIGHT>'` — find the pixel size in `pixelSizes` (`'16:9/2K'` → `'2048x1152'`), so a request's price is `creditsPerImageByTier[quality + '@' + pixelSizes[size + '/' + resolution]]`. Their prompt and reference images are billed as tokens on top. `estimatedDurationMs` sizes a progress indicator; `company` and `strengths` are model-info copy. All optional: absent means the model has nothing to declare, not that the data is missing.
 
 **Tunable engine parameters.** `providerParams` describes what a model exposes for tuning — enough to render a settings panel without hardcoding a thing:
 
@@ -688,7 +691,7 @@ const seed = entity.providerParams?.find((p) => p.key === 'seed');
 await generate({ entityId, prompt, providerParams: { seed: 42 } });
 ```
 
-Nano Banana 2 exposes `seed`, `temperature` (0–2) and `thinking_level` (`'minimal'` default, or `'high'` — the model plans the picture first: better at layouts and directions like "seen from above", slower, and its thinking tokens are billed).
+Nano Banana 2 exposes `seed`, `temperature` (0–2) and `thinking_level` (`'minimal'` default, or `'high'` — the model plans the picture first: better at layouts and directions like "seen from above", slower, and its thinking tokens are billed). The GPT Image models expose `output_format` (`'png'` default, `'jpeg'`, `'webp'`) and `output_compression` (0–100, JPEG and WebP only); GPT Image 1.5 and the GPT Image 2.5 models also take `background` (`'auto'`, `'opaque'`, `'transparent'` — transparent needs PNG or WebP).
 
 **The `category` trap.** A param carrying `category: 'quality'` or `'style'` does NOT belong in `providerParams` — send it on the matching top-level field. Providers read those two from the top level only, and an unrecognized `providerParams` key is dropped without an error, so the image generates at the model's default **and you are billed for it anyway**: