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: imagen-4 (text-to-image), nano-banana-2 (character consistency; the
 * legacy `nano-banana` id is accepted and maps to it), nano-banana-pro (max
 * references, upscale-able). 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.
 */
export declare const FLOW_IMAGE_MODELS: readonly ["imagen-4", "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. useapi renamed `nano-banana` → `nano-banana-2` (it still server-side
 * aliases the old name, but we send the canonical id to stay current).
 */
export declare const FLOW_IMAGE_MODEL_ALIASES: Record<string, FlowImageModel>;
/**
 * Per-model TOTAL reference-image budget — references AND character images
 * share it (verified against the live useapi docs, 2026-06-11): imagen-4
 * accepts at most 3, nano-banana-2 and nano-banana-pro at most 10. This is the
 * hard request budget, distinct from the auto-selection heuristic below.
 */
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`, then validated against
 * FLOW_IMAGE_MODELS); otherwise auto-select from the total reference-image
 * count — 0 refs → imagen-4 (best 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 (imagen-4 ≤3, nano-banana-2(-pro) ≤10) 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