import { type GenImageKind, type GenImageResult } from './gen-image.js';
/**
 * Google Flow image backend for `gen-image` (useapi.net Google Flow API v1,
 * POST /google-flow/images). Direct useapi REST from Node — the same precedent
 * as `native-runway.ts` / `native-dreamina.ts`; it does NOT shell out to the
 * Bun `vclaw-cli` sidecar.
 *
 * Models: nano-banana-2-lite (the API default, fastest text-to-image),
 * nano-banana-2 (character consistency), nano-banana-pro (max references,
 * upscale-able). The legacy ids `nano-banana` and `imagen-4` are accepted and
 * map to `nano-banana-2` / `nano-banana-2-lite`. Reference images are `reference_1..10`
 * mediaGenerationId slots; saved characters are `character_1..7` slots
 * (June-2026 useapi update). The submit auto-solves the reCAPTCHA via
 * `captchaRetry` (see `flow-captcha.ts`). Inline @-markers
 * (`@reference_N` / `@character_N`, case-insensitive) anchor a slot to a
 * position in the prompt — each marker MUST have a matching body slot or the
 * API 400s, so `validateFlowImageMarkers` runs BEFORE any upload or spend.
 */
/**
 * The three models POST /google-flow/images actually generates with.
 *
 * `imagen-4` is NOT among them any more: Google removed Imagen from Flow in
 * July 2026 and useapi kept the id only as a deprecated alias pointing at
 * `nano-banana-2-lite`. We kept sending `imagen-4` for every text-to-image call,
 * so the contract said Imagen while the pixels came from Nano Banana 2 Lite.
 * Naming the real model changes no output — it makes the artifact honest.
 */
export declare const FLOW_IMAGE_MODELS: readonly ["nano-banana-2-lite", "nano-banana-2", "nano-banana-pro"];
export type FlowImageModel = typeof FLOW_IMAGE_MODELS[number];
/**
 * Legacy model ids accepted on input and mapped to the canonical id before the
 * POST — both are still accepted by the API, and both are still typed by
 * operators and sitting in older briefs, so neither is a hard error:
 *   `nano-banana` → `nano-banana-2`   (useapi's 2026 rename)
 *   `imagen-4`    → `nano-banana-2-lite` (Imagen removed from Flow, July 2026)
 */
export declare const FLOW_IMAGE_MODEL_ALIASES: Record<string, FlowImageModel>;
/**
 * Per-model TOTAL reference-image budget — references AND character images
 * share it. **All three models take 10** as of the July 2026 spec; the old
 * 3-reference ceiling belonged to Imagen, and when useapi repointed the
 * `imagen-4` alias at Nano Banana 2 Lite it raised the alias's budget with it.
 * This is the hard request budget, distinct from the auto-selection heuristic
 * below. Kept as a per-model map rather than a constant because it has differed
 * per model before and the spec is free to split it again.
 */
export declare const FLOW_IMAGE_MODEL_REF_BUDGET: Record<FlowImageModel, number>;
/** POST /google-flow/images slot caps. */
export declare const FLOW_IMAGE_MAX_REFERENCES = 10;
export declare const FLOW_IMAGE_MAX_CHARACTERS = 7;
/**
 * Aspect ratios POST /google-flow/images accepts as INPUT. The spec's canonical
 * set is `16:9 / 4:3 / 1:1 / 3:4 / 9:16 / auto`; `landscape`/`portrait` are
 * accepted legacy aliases normalized to `16:9`/`9:16` before the POST (the spec
 * dropped them from the images list).
 */
export declare const FLOW_IMAGE_ASPECTS: string[];
/** Map a legacy `landscape`/`portrait` aspect to its spec-valid ratio (others pass through). */
export declare function normalizeFlowImageAspect(aspect: string): string;
/**
 * Resolve the Flow image model: an explicit id wins (after mapping legacy
 * aliases like `nano-banana` → `nano-banana-2` and `imagen-4` →
 * `nano-banana-2-lite`, then validated against FLOW_IMAGE_MODELS); otherwise
 * auto-select from the total reference-image count — 0 refs →
 * nano-banana-2-lite (the API's own default, fastest pure text-to-image), 1-3 →
 * nano-banana-2 (character consistency), 4+ → nano-banana-pro (max references).
 */
export declare function resolveFlowImageModel(explicit: string | undefined, refCount: number): FlowImageModel;
/**
 * How many reference images a saved-character ref contributes to the per-model
 * budget. Character refs look like `user:1-character:<id>-imgs:N-voice:<v>`;
 * the `-imgs:N-` segment carries the character's image count. Refs without the
 * hint count as 1.
 */
export declare function flowCharacterRefImageCount(ref: string): number;
/**
 * True when a string looks like a saved Flow character ref (the
 * `flow-characters.json` `characterRef` format, e.g.
 * `user:1-character:claw-imgs:1-voice:puck`) rather than a character name.
 * The `-character:` segment is REQUIRED: mediaGenerationIds share the `user:`
 * prefix, so a bare-prefix check would let a `--ref` value pasted into
 * `--character` ship to the API instead of failing fast as character_not_found.
 */
export declare function looksLikeFlowCharacterRef(value: string): boolean;
/**
 * True when a `--ref` value is SHAPED like an already-uploaded Flow media
 * reference (a mediaGenerationId) rather than a local image path. Aligned with
 * `flow-character-library.ts`'s `isMediaRef` so both modules classify the same
 * way. Anything NOT media-shaped is treated as a local path and must exist —
 * classifying by shape (instead of `existsSync` polarity) means a typo'd local
 * path fails fast up front rather than shipping to the provider as a bogus
 * mediaGenerationId after other refs were already uploaded (spend).
 */
export declare function looksLikeFlowMediaRef(value: string): boolean;
/**
 * POST /google-flow/images request body (mirrors the useapi wire shape).
 * `reference_1..10` are mediaGenerationId values; `character_1..7` are saved
 * Flow character refs.
 */
export interface FlowImageParams {
    email: string;
    prompt: string;
    model: FlowImageModel;
    aspectRatio: string;
    count: number;
    seed?: number;
    reference_1?: string;
    reference_2?: string;
    reference_3?: string;
    reference_4?: string;
    reference_5?: string;
    reference_6?: string;
    reference_7?: string;
    reference_8?: string;
    reference_9?: string;
    reference_10?: string;
    character_1?: string;
    character_2?: string;
    character_3?: string;
    character_4?: string;
    character_5?: string;
    character_6?: string;
    character_7?: string;
}
export interface BuildFlowImageParamsOptions {
    prompt: string;
    kind: GenImageKind;
    /** useapi account email carried in the request body. */
    email: string;
    /** Explicit model id; omitted → auto-selected from the total reference count. */
    model?: string;
    /** Defaults per kind (16:9 for screen, 1:1 otherwise). */
    aspectRatio?: string;
    /** Images per generation, 1-4. Defaults to 1 (the API default of 4 would 4x the spend). */
    count?: number;
    /** Seed for reproducible results (non-negative integer). */
    seed?: number;
    /**
     * Values for reference_1..N in order. Validation only depends on the COUNT,
     * so callers may pass not-yet-uploaded local paths for fail-fast/dry-run
     * composition and rebuild with resolved mediaGenerationIds before the POST.
     */
    references?: string[];
    /** Saved Flow character refs for character_1..N in order. */
    characterRefs?: string[];
}
/**
 * Compose the POST /google-flow/images body (PURE — no I/O, no env). Weaves
 * the gen-image per-kind render directive into the prompt (consistent with
 * `buildGenImageRequest`), assigns `reference_1..N` / `character_1..N` slots in
 * input order, and enforces the hard request contract as errors:
 *
 * - ≤10 references, ≤7 characters (slot caps);
 * - model × reference budget (≤10 on every current model) where
 *   character refs COUNT TOWARD the same budget (each contributes its
 *   `-imgs:N-` image count, default 1);
 * - count 1-4, seed ≥0, aspect ratio membership (`auto` needs a nano-banana
 *   model and at least one reference);
 * - every inline @-marker has a matching slot (`validateFlowImageMarkers`).
 */
export declare function buildFlowImageParams(opts: BuildFlowImageParamsOptions): FlowImageParams;
/**
 * Output path for the Nth generated image (1-based): the first goes to
 * `outputPath` verbatim, extras get a `-2`/`-3`/`-4` suffix before the
 * extension. PURE.
 */
export declare function flowOutputPathForIndex(outputPath: string, ordinal: number): string;
export interface FlowGenImageOptions {
    prompt: string;
    kind: GenImageKind;
    /** Where the first resulting image is written (extras get -2/-3/-4 suffixes). */
    outputPath: string;
    /** Explicit model id; omitted → auto-selected from the reference count. */
    model?: string;
    aspectRatio?: string;
    /** Images per generation (1-4, default 1). */
    count?: number;
    seed?: number;
    /**
     * Already-uploaded mediaGenerationIds (media-ref-shaped, passed through) or
     * local image paths (anything else; must exist, uploaded first).
     */
    refs?: string[];
    /** Character names already resolved to saved Flow character refs. */
    characterRefs?: string[];
    /** useapi token; falls back to USEAPI_API_TOKEN. */
    apiToken?: string;
    /** useapi account email; falls back to USEAPI_ACCOUNT_EMAIL. */
    accountEmail?: string;
    /** useapi base URL override (default https://api.useapi.net/v1). */
    baseUrl?: string;
    /** Injectable fetch for tests; defaults to the global fetch. */
    fetcher?: typeof fetch;
    /** captcha-retry auto-solve count; omit → VCLAW_FLOW_CAPTCHA_RETRY (default 3), 0 opts out. */
    captchaRetry?: number;
}
export interface FlowGenImageResult extends GenImageResult {
    /** Every written file in order (paths[0] === path). */
    paths: string[];
    /** mediaGenerationIds of the generated image(s), reusable as reference_N inputs downstream. */
    mediaGenerationIds: string[];
    /** Images requested per generation. */
    count: number;
    /** Seed echoed when one was requested. */
    seed?: number;
    /** mediaGenerationIds minted for uploaded local reference paths (in --ref order). */
    uploadedReferenceIds: string[];
}
/**
 * Generate image(s) via Google Flow and write them to disk. Sequence:
 * validate markers + the model×reference matrix FIRST (zero network on
 * validation failure) → classify refs by shape and fail fast on any
 * non-media-shaped ref whose local path is missing (still zero network) →
 * upload the local reference paths via the existing
 * `FlowLibraryClient.uploadImage` → POST /google-flow/images → download every
 * generated image (first to `outputPath`, extras suffixed -2/-3/-4). Returns
 * the gen-image result shape with `backend: 'flow'` plus the generated
 * `mediaGenerationIds` for downstream reuse.
 */
export declare function generateViaFlow(opts: FlowGenImageOptions): Promise<FlowGenImageResult>;
//# sourceMappingURL=gen-image-flow.d.ts.map