@nodaro/shared 3.57.0 → 3.58.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (118) hide show
  1. package/dist/{chunk-ZSTL4JEJ.cjs → chunk-4UUX62S3.cjs} +12 -12
  2. package/dist/{chunk-ZSTL4JEJ.cjs.map → chunk-4UUX62S3.cjs.map} +1 -1
  3. package/dist/{chunk-JYNW4QK7.cjs → chunk-4ZZ6SVIQ.cjs} +57 -5
  4. package/dist/chunk-4ZZ6SVIQ.cjs.map +1 -0
  5. package/dist/{chunk-O33WVAYQ.cjs → chunk-5PJC4ZWO.cjs} +6 -6
  6. package/dist/{chunk-O33WVAYQ.cjs.map → chunk-5PJC4ZWO.cjs.map} +1 -1
  7. package/dist/{chunk-ZLSPGMES.cjs → chunk-5UVBFY2G.cjs} +11 -11
  8. package/dist/{chunk-ZLSPGMES.cjs.map → chunk-5UVBFY2G.cjs.map} +1 -1
  9. package/dist/{chunk-IQS3WQXQ.js → chunk-6CYS7VRH.js} +56 -6
  10. package/dist/chunk-6CYS7VRH.js.map +1 -0
  11. package/dist/{chunk-D56ALOLY.js → chunk-6TFWFYYI.js} +3 -3
  12. package/dist/{chunk-D56ALOLY.js.map → chunk-6TFWFYYI.js.map} +1 -1
  13. package/dist/{chunk-2LRBQOKA.js → chunk-A5ESI2NY.js} +8 -8
  14. package/dist/{chunk-2LRBQOKA.js.map → chunk-A5ESI2NY.js.map} +1 -1
  15. package/dist/{chunk-EXCZD5ZY.js → chunk-BSENM6HM.js} +3 -3
  16. package/dist/{chunk-EXCZD5ZY.js.map → chunk-BSENM6HM.js.map} +1 -1
  17. package/dist/{chunk-ZPPFPQPO.js → chunk-CNSRCZYY.js} +5 -5
  18. package/dist/{chunk-ZPPFPQPO.js.map → chunk-CNSRCZYY.js.map} +1 -1
  19. package/dist/{chunk-6NZWWMVY.js → chunk-DC2QPACA.js} +4 -4
  20. package/dist/{chunk-6NZWWMVY.js.map → chunk-DC2QPACA.js.map} +1 -1
  21. package/dist/{chunk-ASSJKIZO.cjs → chunk-DCP7JFSE.cjs} +5 -5
  22. package/dist/{chunk-ASSJKIZO.cjs.map → chunk-DCP7JFSE.cjs.map} +1 -1
  23. package/dist/{chunk-MBKJ7IBS.js → chunk-HEUWAIXG.js} +5 -5
  24. package/dist/{chunk-MBKJ7IBS.js.map → chunk-HEUWAIXG.js.map} +1 -1
  25. package/dist/{chunk-2LWHRJPB.cjs → chunk-I7NG2D6X.cjs} +21 -21
  26. package/dist/{chunk-2LWHRJPB.cjs.map → chunk-I7NG2D6X.cjs.map} +1 -1
  27. package/dist/{chunk-P5KH7GAI.cjs → chunk-IKOKRJDI.cjs} +4 -4
  28. package/dist/{chunk-P5KH7GAI.cjs.map → chunk-IKOKRJDI.cjs.map} +1 -1
  29. package/dist/{chunk-QMP3W5GA.js → chunk-IQBIH3AE.js} +3 -3
  30. package/dist/{chunk-QMP3W5GA.js.map → chunk-IQBIH3AE.js.map} +1 -1
  31. package/dist/{chunk-QTTVIQJP.js → chunk-JUEFRVHZ.js} +4 -4
  32. package/dist/{chunk-QTTVIQJP.js.map → chunk-JUEFRVHZ.js.map} +1 -1
  33. package/dist/{chunk-BBMK5XNO.js → chunk-K6UMB37V.js} +3 -3
  34. package/dist/{chunk-BBMK5XNO.js.map → chunk-K6UMB37V.js.map} +1 -1
  35. package/dist/{chunk-5SXI7IYW.cjs → chunk-KYHDKKUJ.cjs} +8 -8
  36. package/dist/{chunk-5SXI7IYW.cjs.map → chunk-KYHDKKUJ.cjs.map} +1 -1
  37. package/dist/{chunk-INGQNLY4.js → chunk-L26G7B27.js} +3 -3
  38. package/dist/{chunk-INGQNLY4.js.map → chunk-L26G7B27.js.map} +1 -1
  39. package/dist/{chunk-UFB36LWU.js → chunk-M7SMSAOU.js} +4 -4
  40. package/dist/{chunk-UFB36LWU.js.map → chunk-M7SMSAOU.js.map} +1 -1
  41. package/dist/{chunk-SWPTF7QJ.js → chunk-ODTZV3BW.js} +4 -4
  42. package/dist/{chunk-SWPTF7QJ.js.map → chunk-ODTZV3BW.js.map} +1 -1
  43. package/dist/{chunk-KZTXGMVH.js → chunk-OMUYZKRB.js} +3 -3
  44. package/dist/{chunk-KZTXGMVH.js.map → chunk-OMUYZKRB.js.map} +1 -1
  45. package/dist/{chunk-ALVO5Q36.cjs → chunk-PK4ZR2SK.cjs} +4 -4
  46. package/dist/{chunk-ALVO5Q36.cjs.map → chunk-PK4ZR2SK.cjs.map} +1 -1
  47. package/dist/chunk-QCW6J6BQ.cjs +27 -0
  48. package/dist/{chunk-RKTWLAJO.cjs.map → chunk-QCW6J6BQ.cjs.map} +1 -1
  49. package/dist/{chunk-D5J332XS.cjs → chunk-QPBBIRLF.cjs} +39 -39
  50. package/dist/{chunk-D5J332XS.cjs.map → chunk-QPBBIRLF.cjs.map} +1 -1
  51. package/dist/{chunk-FFW2HTR2.cjs → chunk-QVPIO2NU.cjs} +5 -5
  52. package/dist/{chunk-FFW2HTR2.cjs.map → chunk-QVPIO2NU.cjs.map} +1 -1
  53. package/dist/{chunk-BH2IDJVO.cjs → chunk-S5VBJJUT.cjs} +46 -46
  54. package/dist/{chunk-BH2IDJVO.cjs.map → chunk-S5VBJJUT.cjs.map} +1 -1
  55. package/dist/{chunk-R5GOPHYB.js → chunk-SEQ5L72K.js} +5 -4
  56. package/dist/chunk-SEQ5L72K.js.map +1 -0
  57. package/dist/{chunk-3SH5ZUNJ.js → chunk-VVGSIWNL.js} +4 -4
  58. package/dist/{chunk-3SH5ZUNJ.js.map → chunk-VVGSIWNL.js.map} +1 -1
  59. package/dist/{chunk-4KKFO6YR.cjs → chunk-VZXRDSWA.cjs} +23 -21
  60. package/dist/chunk-VZXRDSWA.cjs.map +1 -0
  61. package/dist/{chunk-R3OIZ2BM.cjs → chunk-WBERPAXE.cjs} +6 -6
  62. package/dist/{chunk-R3OIZ2BM.cjs.map → chunk-WBERPAXE.cjs.map} +1 -1
  63. package/dist/{chunk-OHQBQOGH.cjs → chunk-WLFT5UVV.cjs} +8 -8
  64. package/dist/{chunk-OHQBQOGH.cjs.map → chunk-WLFT5UVV.cjs.map} +1 -1
  65. package/dist/{chunk-C3E6UZS4.js → chunk-ZMH56CLL.js} +3 -3
  66. package/dist/{chunk-C3E6UZS4.js.map → chunk-ZMH56CLL.js.map} +1 -1
  67. package/dist/{chunk-NJTLBZIP.cjs → chunk-ZX6RRM6R.cjs} +43 -43
  68. package/dist/{chunk-NJTLBZIP.cjs.map → chunk-ZX6RRM6R.cjs.map} +1 -1
  69. package/dist/entries/apps.cjs +42 -42
  70. package/dist/entries/apps.js +7 -7
  71. package/dist/entries/credits.cjs +150 -150
  72. package/dist/entries/credits.d.cts +1 -1
  73. package/dist/entries/credits.d.ts +1 -1
  74. package/dist/entries/credits.js +7 -7
  75. package/dist/entries/llm-models.d.cts +1 -1
  76. package/dist/entries/llm-models.d.ts +1 -1
  77. package/dist/entries/model-catalog.cjs +76 -68
  78. package/dist/entries/model-catalog.d.cts +2 -2
  79. package/dist/entries/model-catalog.d.ts +2 -2
  80. package/dist/entries/model-catalog.js +4 -4
  81. package/dist/entries/models.cjs +291 -287
  82. package/dist/entries/models.d.cts +3 -3
  83. package/dist/entries/models.d.ts +3 -3
  84. package/dist/entries/models.js +4 -4
  85. package/dist/entries/nodes.cjs +206 -206
  86. package/dist/entries/nodes.d.cts +1 -1
  87. package/dist/entries/nodes.d.ts +1 -1
  88. package/dist/entries/nodes.js +8 -8
  89. package/dist/entries/pipeline.cjs +152 -152
  90. package/dist/entries/pipeline.d.cts +1 -1
  91. package/dist/entries/pipeline.d.ts +1 -1
  92. package/dist/entries/pipeline.js +3 -3
  93. package/dist/entries/ugc.cjs +71 -71
  94. package/dist/entries/ugc.js +4 -4
  95. package/dist/entries/video.cjs +117 -117
  96. package/dist/entries/video.js +4 -4
  97. package/dist/index.cjs +1081 -1069
  98. package/dist/index.d.cts +2 -2
  99. package/dist/index.d.ts +2 -2
  100. package/dist/index.js +17 -17
  101. package/dist/{model-catalog-CwkG9xi-.d.ts → model-catalog-CCsA1isC.d.cts} +51 -11
  102. package/dist/{model-catalog-CwkG9xi-.d.cts → model-catalog-CCsA1isC.d.ts} +51 -11
  103. package/dist/{model-constants-BbsZSVTA.d.cts → model-constants-BtXkUsX3.d.cts} +14 -2
  104. package/dist/{model-constants-BbsZSVTA.d.ts → model-constants-BtXkUsX3.d.ts} +14 -2
  105. package/package.json +1 -1
  106. package/src/__tests__/auto-aspect-source.test.ts +93 -0
  107. package/src/__tests__/normalize-model-input.test.ts +62 -8
  108. package/src/__tests__/resolutions-by-aspect-ratio.test.ts +134 -0
  109. package/src/__tests__/video-frame-slot.test.ts +5 -0
  110. package/src/entries/model-catalog.ts +2 -0
  111. package/src/entries/models.ts +1 -0
  112. package/src/model-catalog.ts +122 -17
  113. package/src/model-constants.ts +14 -1
  114. package/dist/chunk-4KKFO6YR.cjs.map +0 -1
  115. package/dist/chunk-IQS3WQXQ.js.map +0 -1
  116. package/dist/chunk-JYNW4QK7.cjs.map +0 -1
  117. package/dist/chunk-R5GOPHYB.js.map +0 -1
  118. package/dist/chunk-RKTWLAJO.cjs +0 -27
@@ -312,10 +312,31 @@ export interface ModelCatalogEntry {
312
312
  * Declared only where the provider documents its own form: Grok Imagine's
313
313
  * `@image(n)` (docs.kie.ai/market/grok-imagine/image-to-video) and
314
314
  * HappyHorse's `[Image N]` (docs.kie.ai/market/happyhorse-1-1/reference-to-video).
315
+ * Gemini Omni Flash 1.2 documents none and is written plain `image N`, the
316
+ * form of KIE's own example; beside references its frames only guide the
317
+ * clip, in either wording.
315
318
  */
316
- referenceSyntax?: "@image(n)" | "[Image N]"
319
+ referenceSyntax?: "@image(n)" | "[Image N]" | "image N"
317
320
  aspectRatios?: readonly string[]
321
+ /**
322
+ * The model lists "auto", but its own auto does not keep the photo's shape
323
+ * (GPT Image 2.6 renders a portrait square). "auto" with a photo is then
324
+ * resolved as on a model without a native auto: to the listed ratio nearest
325
+ * the photo (`autoAspectNeedsSourceImage`, `normalizeModelInput`). With no
326
+ * photo, or one whose size cannot be read, the model's own "auto" is sent,
327
+ * as before. "auto" stays in `aspectRatios`, so every menu still offers it.
328
+ */
329
+ autoAspectFromSourceImage?: true
318
330
  resolutions?: readonly string[]
331
+ /**
332
+ * The aspect ratios at which this model renders fewer sizes than
333
+ * `resolutions`: each one names the sizes it renders, in the catalog's own
334
+ * spelling. A ratio not listed renders every entry of `resolutions`.
335
+ * `normalizeModelInput` moves a size such a ratio does not render to the
336
+ * largest one it does at or below it, and says so, before the run is priced;
337
+ * a menu reads the sizes on offer with `resolutionsAtAspectRatio`.
338
+ */
339
+ resolutionsByAspectRatio?: Readonly<Record<string, readonly string[]>>
319
340
  /** The resolution a caller who names none lands on when it is not the
320
341
  * cheapest entry (see `defaultResolutionFor`). */
321
342
  defaultResolution?: string
@@ -482,15 +503,23 @@ const GPT_IMAGE_RATIOS = ["1:1", "3:2", "2:3"] as const
482
503
  const GPT_IMAGE_2_RATIOS = ["auto", "1:1", "16:9", "9:16", "4:3", "3:4"] as const
483
504
  // GPT Image 2.5 (Flare + Sunburst) widen the set to thirteen — the GPT Image 2
484
505
  // six plus 3:2/2:3, ultra-wide 21:9/27:16, ultra-tall 16:27 and near-square
485
- // 9:8/8:9 (docs.kie.ai/market/gpt/gpt-image-2-5-*). Unlike GPT Image 2, the 2.5
486
- // docs state NO aspect-ratio x resolution restriction, so no cross-field
487
- // constraint is registered for these ids in normalizeModelInput below.
506
+ // 9:8/8:9 (docs.kie.ai/market/gpt/gpt-image-2-5-*).
488
507
  const GPT_IMAGE_2_5_RATIOS = [
489
508
  "auto", "1:1", "3:2", "2:3", "4:3", "3:4", "16:9", "9:16",
490
509
  "21:9", "27:16", "16:27", "9:8", "8:9",
491
510
  ] as const
511
+ // GPT Image 2.5 renders 27:16, 16:27, 9:8 and 8:9 at 1K only; 2K and 4K are for
512
+ // its other ratios (the aspect_ratio field of every 2.5 page: Flare and
513
+ // Sunburst, text-to-image and image-to-image). `normalizeModelInput` moves a
514
+ // larger size there to 1K before the run is priced.
515
+ const GPT_IMAGE_2_5_RESOLUTIONS_BY_RATIO = {
516
+ "27:16": ["1K"], "16:27": ["1K"], "9:8": ["1K"], "8:9": ["1K"],
517
+ } as const
492
518
  // GPT Image 2.6 Flare and Sunburst: auto plus fifteen ratios, Economy a shorter
493
- // list of its own (docs.kie.ai/market/gpt/gpt-image-2-6-*).
519
+ // list of its own (docs.kie.ai/market/gpt/gpt-image-2-6-*). Every 2.6 entry
520
+ // carries `autoAspectFromSourceImage`: 2.6's own auto renders a portrait photo
521
+ // square (measured 2026-11-10: 768x1024 in, 1024x1024 out; 2.5's auto kept
522
+ // it at 3:4), so "auto" with a photo is sent as the ratio nearest the photo.
494
523
  const GPT_IMAGE_2_6_RATIOS = [
495
524
  "auto", "1:1", "3:2", "2:3", "4:3", "3:4", "5:4", "4:5", "16:9", "9:16",
496
525
  "2:1", "1:2", "21:9", "9:21", "3:1", "1:3",
@@ -926,6 +955,7 @@ const IMAGE_MODELS: Record<string, ModelCatalogEntry> = {
926
955
  features: ["reference-image"],
927
956
  aspectRatios: GPT_IMAGE_2_5_RATIOS,
928
957
  resolutions: ["1K", "2K", "4K"],
958
+ resolutionsByAspectRatio: GPT_IMAGE_2_5_RESOLUTIONS_BY_RATIO,
929
959
  backgrounds: GPT_IMAGE_BACKGROUNDS,
930
960
  transparentResolution: "1K",
931
961
  backgroundOnlyAtTransparentResolution: true,
@@ -954,6 +984,7 @@ const IMAGE_MODELS: Record<string, ModelCatalogEntry> = {
954
984
  features: ["reference-image"],
955
985
  aspectRatios: GPT_IMAGE_2_5_RATIOS,
956
986
  resolutions: ["1K", "2K", "4K"],
987
+ resolutionsByAspectRatio: GPT_IMAGE_2_5_RESOLUTIONS_BY_RATIO,
957
988
  backgrounds: GPT_IMAGE_BACKGROUNDS,
958
989
  transparentResolution: "1K",
959
990
  backgroundOnlyAtTransparentResolution: true,
@@ -982,6 +1013,7 @@ const IMAGE_MODELS: Record<string, ModelCatalogEntry> = {
982
1013
  features: ["reference-image"],
983
1014
  aspectRatios: GPT_IMAGE_2_5_RATIOS,
984
1015
  resolutions: ["1K", "2K", "4K"],
1016
+ resolutionsByAspectRatio: GPT_IMAGE_2_5_RESOLUTIONS_BY_RATIO,
985
1017
  backgrounds: GPT_IMAGE_BACKGROUNDS,
986
1018
  transparentResolution: "1K",
987
1019
  backgroundOnlyAtTransparentResolution: true,
@@ -1010,6 +1042,7 @@ const IMAGE_MODELS: Record<string, ModelCatalogEntry> = {
1010
1042
  features: ["reference-image"],
1011
1043
  aspectRatios: GPT_IMAGE_2_5_RATIOS,
1012
1044
  resolutions: ["1K", "2K", "4K"],
1045
+ resolutionsByAspectRatio: GPT_IMAGE_2_5_RESOLUTIONS_BY_RATIO,
1013
1046
  backgrounds: GPT_IMAGE_BACKGROUNDS,
1014
1047
  transparentResolution: "1K",
1015
1048
  backgroundOnlyAtTransparentResolution: true,
@@ -1037,6 +1070,7 @@ const IMAGE_MODELS: Record<string, ModelCatalogEntry> = {
1037
1070
  useCases: ["typography", "high-res", "general", "draft"],
1038
1071
  features: ["reference-image"],
1039
1072
  aspectRatios: GPT_IMAGE_2_6_RATIOS,
1073
+ autoAspectFromSourceImage: true,
1040
1074
  resolutions: ["1K", "2K", "4K"],
1041
1075
  qualities: ["auto", "low", "medium", "high", "xhigh", "max"],
1042
1076
  defaultQuality: "medium",
@@ -1078,6 +1112,7 @@ const IMAGE_MODELS: Record<string, ModelCatalogEntry> = {
1078
1112
  useCases: ["edit", "high-res"],
1079
1113
  features: ["reference-image"],
1080
1114
  aspectRatios: GPT_IMAGE_2_6_RATIOS,
1115
+ autoAspectFromSourceImage: true,
1081
1116
  resolutions: ["1K", "2K", "4K"],
1082
1117
  qualities: ["auto", "low", "medium", "high", "xhigh", "max"],
1083
1118
  defaultQuality: "medium",
@@ -1106,6 +1141,7 @@ const IMAGE_MODELS: Record<string, ModelCatalogEntry> = {
1106
1141
  useCases: ["typography", "high-res", "general"],
1107
1142
  features: ["reference-image"],
1108
1143
  aspectRatios: GPT_IMAGE_2_6_RATIOS,
1144
+ autoAspectFromSourceImage: true,
1109
1145
  resolutions: ["1K", "2K", "4K"],
1110
1146
  qualities: ["auto", "low", "medium", "high", "xhigh", "max"],
1111
1147
  defaultQuality: "medium",
@@ -1147,6 +1183,7 @@ const IMAGE_MODELS: Record<string, ModelCatalogEntry> = {
1147
1183
  useCases: ["edit", "high-res"],
1148
1184
  features: ["reference-image"],
1149
1185
  aspectRatios: GPT_IMAGE_2_6_RATIOS,
1186
+ autoAspectFromSourceImage: true,
1150
1187
  resolutions: ["1K", "2K", "4K"],
1151
1188
  qualities: ["auto", "low", "medium", "high", "xhigh", "max"],
1152
1189
  defaultQuality: "medium",
@@ -1181,6 +1218,7 @@ const IMAGE_MODELS: Record<string, ModelCatalogEntry> = {
1181
1218
  useCases: ["general", "draft"],
1182
1219
  features: ["reference-image"],
1183
1220
  aspectRatios: GPT_IMAGE_2_6_ECONOMY_RATIOS,
1221
+ autoAspectFromSourceImage: true,
1184
1222
  backgrounds: GPT_IMAGE_BACKGROUNDS,
1185
1223
  pricing: [{ identifier: "gpt-image-2-6-economy", credits: 13, note: "1K flat" }],
1186
1224
  valueLabels: GPT_IMAGE_2_6_VALUE_LABELS,
@@ -1199,6 +1237,7 @@ const IMAGE_MODELS: Record<string, ModelCatalogEntry> = {
1199
1237
  useCases: ["edit", "draft"],
1200
1238
  features: ["reference-image"],
1201
1239
  aspectRatios: GPT_IMAGE_2_6_ECONOMY_RATIOS,
1240
+ autoAspectFromSourceImage: true,
1202
1241
  backgrounds: GPT_IMAGE_BACKGROUNDS,
1203
1242
  pricing: [{ identifier: "gpt-image-2-6-economy-i2i", credits: 13, note: "1K flat" }],
1204
1243
  valueLabels: GPT_IMAGE_2_6_VALUE_LABELS,
@@ -1940,6 +1979,7 @@ const VIDEO_MODELS: Record<string, ModelCatalogEntry> = {
1940
1979
  description: "Google Gemini Omni Flash 1.2 — 3–15s video with native sound, from 360p to 4K: from text, up to 6 reference images, exact first and last frames, or a video edit. Priced per second.",
1941
1980
  useCases: ["cinematic", "fast"],
1942
1981
  features: ["audio", "reference-image", "reference-to-video", "end-frame"],
1982
+ referenceSyntax: "image N",
1943
1983
  aspectRatios: ["16:9", "9:16", "auto"],
1944
1984
  resolutions: ["360p", "720p", "1080p", "4k"],
1945
1985
  defaultResolution: "720p",
@@ -4004,8 +4044,9 @@ export interface SourceImageSize {
4004
4044
  export interface ModelInputContext {
4005
4045
  /**
4006
4046
  * The image an image-to-image or edit request transforms. Only read to
4007
- * resolve "auto" on a model without a native auto; absent or unusable means
4008
- * the size is unknown and "auto" snaps the way it always has.
4047
+ * resolve "auto" on a model without a native auto, or whose own auto does
4048
+ * not keep the photo's shape (`autoAspectFromSourceImage`); absent or
4049
+ * unusable means the size is unknown and "auto" snaps the way it always has.
4009
4050
  */
4010
4051
  sourceImage?: SourceImageSize
4011
4052
  }
@@ -4066,14 +4107,59 @@ export function nearestCatalogAspectRatio(
4066
4107
 
4067
4108
  /**
4068
4109
  * True when `aspectRatio` is "auto" and `modelId`'s catalog ratio list does not
4069
- * carry "auto" — the one case where the source image's size decides the ratio.
4070
- * A caller that has to fetch the size asks this first, so a request that will
4071
- * not use it never pays for the read.
4110
+ * carry "auto", or carries it but the model's own auto does not keep the
4111
+ * photo's shape (`autoAspectFromSourceImage`) — the cases where the source
4112
+ * image's size decides the ratio. A caller that has to fetch the size asks
4113
+ * this first, so a request that will not use it never pays for the read.
4072
4114
  */
4073
4115
  export function autoAspectNeedsSourceImage(modelId: string | undefined, aspectRatio: unknown): boolean {
4074
4116
  if (!modelId || !isAutoAspectToken(aspectRatio)) return false
4075
- const ratios = MODEL_CATALOG[modelId]?.aspectRatios
4076
- return ratios !== undefined && ratios.length > 0 && !ratios.some(isAutoAspectToken)
4117
+ const entry = MODEL_CATALOG[modelId]
4118
+ const ratios = entry?.aspectRatios
4119
+ if (ratios === undefined || ratios.length === 0) return false
4120
+ return entry?.autoAspectFromSourceImage === true || !ratios.some(isAutoAspectToken)
4121
+ }
4122
+
4123
+ /**
4124
+ * The sizes `modelId` renders at `aspectRatio`, in the catalog's order: its
4125
+ * `resolutions`, narrowed where `resolutionsByAspectRatio` lists that ratio.
4126
+ * `undefined` for an unknown model or one with no size setting. What a menu
4127
+ * offers once a ratio is chosen.
4128
+ */
4129
+ export function resolutionsAtAspectRatio(modelId: string, aspectRatio: unknown): readonly string[] | undefined {
4130
+ const m = MODEL_CATALOG[modelId]
4131
+ const all = m?.resolutions
4132
+ if (!all || all.length === 0) return undefined
4133
+ const byRatio = m.resolutionsByAspectRatio
4134
+ const ratio = typeof aspectRatio === "string" ? aspectRatio.trim() : undefined
4135
+ // Own keys only: a ratio such as "constructor" must not read the prototype.
4136
+ const only = byRatio && ratio !== undefined && Object.prototype.hasOwnProperty.call(byRatio, ratio)
4137
+ ? byRatio[ratio]
4138
+ : undefined
4139
+ return only ? all.filter((r) => only.includes(r)) : all
4140
+ }
4141
+
4142
+ /**
4143
+ * The size `modelId` renders `resolution` at, at `aspectRatio`: the same size
4144
+ * where that ratio renders it (or the model limits no ratio), else the largest
4145
+ * size the ratio renders at or below it, else its smallest. A size the model
4146
+ * does not list comes back as it is: snapping the lever itself is
4147
+ * `normalizeModelInput`'s. A route that prices a run without that function
4148
+ * prices and sends the size this returns, so the two agree.
4149
+ */
4150
+ export function resolutionAtAspectRatio(
4151
+ modelId: string,
4152
+ aspectRatio: unknown,
4153
+ resolution: string | undefined,
4154
+ ): string | undefined {
4155
+ if (resolution === undefined) return undefined
4156
+ const all = MODEL_CATALOG[modelId]?.resolutions
4157
+ const offered = resolutionsAtAspectRatio(modelId, aspectRatio)
4158
+ if (!all || !offered || offered.length === 0 || offered.includes(resolution)) return resolution
4159
+ const at = all.indexOf(resolution)
4160
+ if (at < 0) return resolution
4161
+ const atOrBelow = offered.filter((r) => all.indexOf(r) <= at)
4162
+ return atOrBelow.length > 0 ? atOrBelow[atOrBelow.length - 1]! : offered[0]!
4077
4163
  }
4078
4164
 
4079
4165
  /**
@@ -4090,10 +4176,11 @@ export function autoAspectNeedsSourceImage(modelId: string | undefined, aspectRa
4090
4176
  *
4091
4177
  * Rules, mirroring the config panels' provider-change snap:
4092
4178
  * - Model has no such lever → drop the value (sending it 400s upstream).
4093
- * - "auto" on a model whose list lacks it, with a known `context.sourceImage`
4094
- * → the listed ratio nearest the source's shape (`nearestCatalogAspectRatio`).
4095
- * "auto" asks to keep the source photo's shape; the first listed ratio
4096
- * would reframe every source of another shape.
4179
+ * - "auto" on a model whose list lacks it, or whose own auto does not keep
4180
+ * the photo's shape (`autoAspectFromSourceImage`), with a known
4181
+ * `context.sourceImage` → the listed ratio nearest the source's shape
4182
+ * (`nearestCatalogAspectRatio`). "auto" asks to keep the source photo's
4183
+ * shape; the first listed ratio would reframe every source of another shape.
4097
4184
  * - Value outside the model's allow-list → snap to the model's default
4098
4185
  * (`defaultResolutionFor`) or the first valid option.
4099
4186
  * - Then apply cross-field constraints that only hold for certain models.
@@ -4162,11 +4249,14 @@ export function normalizeModelInput(
4162
4249
  : undefined
4163
4250
  if (sourceRatio !== undefined && input.aspectRatio !== undefined) {
4164
4251
  const { width, height } = context.sourceImage!
4252
+ const why = m.autoAspectFromSourceImage === true
4253
+ ? `${m.label}'s own "auto" does not keep the photo's shape`
4254
+ : `${m.label} has no "auto" aspect ratio`
4165
4255
  adjustments.push({
4166
4256
  field: "aspectRatio",
4167
4257
  from: input.aspectRatio,
4168
4258
  to: sourceRatio,
4169
- reason: `${m.label} has no "auto" aspect ratio — using "${sourceRatio}", the supported ratio closest to the source image's shape (${width}x${height}).`,
4259
+ reason: `${why} — using "${sourceRatio}", the supported ratio closest to the source image's shape (${width}x${height}).`,
4170
4260
  })
4171
4261
  out.aspectRatio = sourceRatio
4172
4262
  } else {
@@ -4185,6 +4275,21 @@ export function normalizeModelInput(
4185
4275
  ? input.duration
4186
4276
  : snap("duration", input.duration, m.durations)
4187
4277
 
4278
+ // A size the chosen ratio does not render (`resolutionsByAspectRatio`) moves
4279
+ // to the largest one it does at or below it. Before the background rules
4280
+ // below, which read the size this leaves, and before any price is built.
4281
+ const sized = resolutionAtAspectRatio(modelId, out.aspectRatio, out.resolution)
4282
+ if (out.resolution !== undefined && sized !== undefined && sized !== out.resolution) {
4283
+ const offered = resolutionsAtAspectRatio(modelId, out.aspectRatio) ?? [sized]
4284
+ adjustments.push({
4285
+ field: "resolution",
4286
+ from: out.resolution,
4287
+ to: sized,
4288
+ reason: `${m.label} only renders ${offered.join(" or ")} at the "${out.aspectRatio}" aspect ratio.`,
4289
+ })
4290
+ out.resolution = sized
4291
+ }
4292
+
4188
4293
  // Cross-field constraints — a pair that is individually valid but jointly
4189
4294
  // rejected upstream. GPT Image 2 (per docs.kie.ai): `auto` requires 1K, and
4190
4295
  // 1:1 cannot go to 4K. Applied last so it sees the already-snapped values.
@@ -226,6 +226,19 @@ export const PROMPT_HARD_CEILING = 30000
226
226
  */
227
227
  export const LLM_TEXT_INPUT_MAX = 100_000
228
228
 
229
+ /**
230
+ * Ceiling for the `system` prompt of the structured-output routes
231
+ * (`POST /v1/llm/structured` and `POST /v1/llm/structured/jobs`). A client
232
+ * that has the model write in its own vocabulary sends that vocabulary as the
233
+ * system prompt, and it grows with the client's catalogs (Nodaro Studio's
234
+ * production format is close to 100,000 chars), so this is twice
235
+ * {@link LLM_TEXT_INPUT_MAX}. The routes' `input`, and every other LLM text
236
+ * field, stay at LLM_TEXT_INPUT_MAX. 200,000 chars is roughly 50,000 to
237
+ * 100,000 tokens, and a body at both ceilings still fits the API's 1 MB
238
+ * request limit.
239
+ */
240
+ export const LLM_STRUCTURED_SYSTEM_MAX = 200_000
241
+
229
242
  /**
230
243
  * Per-provider maximum VIDEO prompt length (chars), VERIFIED against each model's
231
244
  * official docs.kie.ai schema (2026-06). Absent → {@link VIDEO_PROMPT_MAX} (8000)
@@ -1194,7 +1207,7 @@ export function resolveVideoModeForInputs(
1194
1207
  }
1195
1208
 
1196
1209
  /** The prompt syntax a video provider addresses its images in, by array order. */
1197
- export type VideoReferenceSyntax = "@image_N" | "@image(n)" | "[Image N]"
1210
+ export type VideoReferenceSyntax = "@image_N" | "@image(n)" | "[Image N]" | "image N"
1198
1211
 
1199
1212
  /**
1200
1213
  * The syntax this video model's frame / identity binding sentences are written