@molecule/api-ai-image-generation-pipeline

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

@molecule/api-ai-image-generation-pipeline — high-level pipeline wrapping @molecule/api-ai-image-generation (vendor abstraction) with style application, brand-model mapping, base64-to-data-URL normalization, and chat-driven prompt enhancement.

Extracted from the ai-image-generator flagship. Use it when you need end-to-end "user types prompt → image" semantics with graceful fallback when no provider is bonded.

Quick Start

import { runImageGeneration, enhancePrompt } from '@molecule/api-ai-image-generation-pipeline'

const enhanced = await enhancePrompt({ prompt: 'a cat' })
const result = await runImageGeneration({
  prompt: enhanced.text,
  size: '1024x1024',
  stylePromptModifier: 'photorealistic, golden hour lighting',
  model: 'reverie-xl-v3',
  provider: 'openai',
})
if (result.status === 'succeeded') console.log(result.imageUrl)

Type

utility

Installation

npm install @molecule/api-ai-image-generation-pipeline @molecule/api-ai @molecule/api-ai-image-generation

API

Interfaces

EnhancePromptOptions

Options accepted by {@link enhancePrompt}.

interface EnhancePromptOptions {
  prompt: string
  /** AI provider name (e.g. 'anthropic'); falls back to default-bonded provider. */
  providerName?: string
  /** Override system instructions for the rewrite. */
  system?: string
  maxTokens?: number
  temperature?: number
}

EnhancePromptResult

Result returned by {@link enhancePrompt}.

interface EnhancePromptResult {
  text: string
  enhanced: boolean
}

ImageGenerationOutcome

Normalized outcome returned by {@link runImageGeneration} for all terminal states.

interface ImageGenerationOutcome {
  imageUrl: string | null
  revisedPrompt: string | null
  status: GenerationStatus
  error: string | null
}

RunImageGenerationOptions

Options accepted by {@link runImageGeneration}.

interface RunImageGenerationOptions {
  prompt: string
  size?: string
  style?: string
  model?: string
  provider?: string
  /** Style modifier appended to the prompt before vendor dispatch. */
  stylePromptModifier?: string | null
  /** Optional brand→vendor model translation; defaults to {@link defaultResolveModel}. */
  resolveModel?: (brandModel: string | undefined, provider: string) => string | undefined
}

Types

GenerationStatus

Union of terminal + intermediate image-generation states.

type GenerationStatus = 'succeeded' | 'failed' | 'queued'

Functions

applyStyleToPrompt(prompt, modifier)

Append a style modifier onto the user-typed prompt.

function applyStyleToPrompt(prompt: string, modifier: string | null | undefined): string

defaultResolveModel(brandModel, provider)

Default brand-to-provider model mapper used by the flagship. Override via {@link RunImageGenerationOptions.resolveModel}.

function defaultResolveModel(brandModel: string | undefined, provider: string): string | undefined

enhancePrompt(opts)

Expand a short user prompt into a richer one via the bonded chat AI provider. Returns { enhanced: false, text: prompt } if no provider is bonded or the stream errors — the endpoint stays contractually 200 so the calling UI flow remains testable without an AI key.

function enhancePrompt(opts: EnhancePromptOptions): Promise<EnhancePromptResult>

runImageGeneration(opts)

Dispatch the bonded image-generation provider and normalize output. Returns status: 'queued' if no provider is bonded (graceful no-op), status: 'failed' with an error if the provider throws or returns no image, and status: 'succeeded' with an imageUrl otherwise.

Base64 responses (e.g. gpt-image-1) are normalized to a data: URL.

function runImageGeneration(opts: RunImageGenerationOptions): Promise<ImageGenerationOutcome>

Injection Notes

Requirements

Peer dependencies:

• @molecule/api-ai ^1.0.1
• @molecule/api-ai-image-generation ^1.0.1

Runtime Dependencies

• @molecule/api-ai
• @molecule/api-ai-image-generation

Wiring — this package composes TWO different accessor mechanisms:

• runImageGeneration() resolves @molecule/api-ai-image-generation, whose core keeps its OWN singleton: wire it with THAT package's setProvider(...) (e.g. setProvider(createProvider()) from @molecule/api-ai-image-generation-openai). A generic bond('ai-image-generation', …) call is never seen by that core — the pipeline then returns status: 'queued' forever with no error to debug.
• enhancePrompt() resolves the registry-based @molecule/api-ai chat bond (bond('ai', provider) / named providers); with none bonded it returns { enhanced: false, text: prompt } instead of failing.

status: 'queued' means "no image provider wired" (the graceful no-op path), NOT "an async job is pending" — nothing retries it. Treat a persistent 'queued' as a wiring bug.