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

molecule.dev hosted image generation provider — images billed to your molecule project, no vendor account

Type

provider

Installation

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

API

Interfaces

MoleculeImageGenerationConfig

Options for createProvider. Every field falls back to an env var, so the zero-argument provider export works from .env alone.

interface MoleculeImageGenerationConfig {
  /**
   * The molecule project API key (`mk_…`), or the sandbox token molecule.dev
   * writes for in-IDE apps (`mbk_…`). Defaults to `MOLECULE_API_KEY`.
   */
  apiKey?: string
  /**
   * The hosted services base URL, without a trailing slash. Defaults to
   * `MOLECULE_SERVICES_URL`, then `https://api.molecule.dev/api/v1/services`.
   */
  servicesUrl?: string
  /**
   * Per-request timeout in milliseconds. Default 120000 — image generation is
   * slow (a 1536x1024 `high` image can take tens of seconds), so unlike the
   * other hosted bonds 15 seconds is not enough.
   */
  timeoutMs?: number
}

ProcessEnv

Environment variables this provider reads.

interface ProcessEnv {
  MOLECULE_API_KEY?: string
  MOLECULE_SERVICES_URL?: string
}

Classes

MoleculeImageGenerationProvider

Image generation provider backed by molecule.dev's hosted service.

Only generate is implemented: the hosted service serves text-to-image. edit/imageToImage/upscale are optional methods on the core contract and are absent here — feature-detect (if (provider.edit)) as the core's own remarks prescribe.

MoleculeServiceError

Error thrown for a refused or failed hosted-service call.

Functions

createProvider(config)

Create a hosted image generation provider.

function createProvider(config?: MoleculeImageGenerationConfig): AIImageGenerationProvider

• config — Options; each falls back to its env var.

Returns: An AIImageGenerationProvider backed by molecule.dev.

Constants

aiImageGenerationMoleculeSecretDefinitions

Secret definitions required by the molecule.dev hosted image generation bond.

const aiImageGenerationMoleculeSecretDefinitions: SecretDefinition[]

DEFAULT_SERVICES_URL

Default hosted services base URL.

const DEFAULT_SERVICES_URL: 'https://api.molecule.dev/api/v1/services'

IMAGE_GENERATION_SERVICE_LIMITS

Per-request limits of the hosted service (mirrored locally, before any request).

const IMAGE_GENERATION_SERVICE_LIMITS: {
  readonly maxPromptChars: 2000
  readonly maxImages: 4
  readonly models: readonly ['gpt-image-1.5', 'gpt-image-1', 'gpt-image-1-mini']
  readonly sizes: readonly ['1024x1024', '1024x1536', '1536x1024']
  readonly qualities: readonly ['low', 'medium', 'high']
}

provider

The provider implementation (wire with setProvider).

const provider: AIImageGenerationProvider

Core Interface

Implements @molecule/api-ai-image-generation interface.

Bond Wiring

Setup function to register this provider with the core interface:

import { setProvider } from '@molecule/api-ai-image-generation'
import { provider } from '@molecule/api-ai-image-generation-molecule'

export function setupAiImageGenerationMolecule(): void {
  setProvider(provider)
}

Injection Notes

Requirements

Peer dependencies:

• @molecule/api-ai-image-generation >=1.0.2
• @molecule/api-secrets ^1.0.1

Environment Variables

• MOLECULE_API_KEY (required) — molecule.dev project API key
  • Setup: Create one for your project with mlcl apikey create --project <id> --name <name> (keys start with mk_).
  • Get it here: https://www.molecule.dev
  • Example: mk_...

Runtime Dependencies

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

E2E Tests

Integration checklist — drive the real UI (live preview, no mocks), adapt each item to this app's actual screens/flows, and check every box off one by one. A box you can't check is an integration bug to fix — not a skip:

• Entering a prompt in the UI and submitting produces a REAL rendered image in the live preview — not a broken img (image icon / alt text), a grey placeholder, or an error toast. Confirm the img element actually decoded (its naturalWidth/naturalHeight are non-zero) and the picture visibly reflects the prompt (a "red bicycle" prompt shows a red bicycle).
• Two different prompts produce two visibly different images — a fixed stub, or a cached first result that never changes, is a broken integration.
• The image is STORED AND SERVED FROM THE APP'S OWN ORIGIN: the rendered img src (and any saved record) points at the app's uploads/storage, not the provider's temporary URL. Provider url results expire — reload the page (or revisit the record later) and the image must still load. Download the provider result server-side and persist it (uploads bond); never hotlink the provider URL — it 404s later and can leak the API request context. (base64/data results must likewise be saved, not held only in the response.)
• Any exposed generation options take effect: changing size/dimensions yields a differently-sized image; requesting a count (n) of N renders N images. If the UI exposes no such options, this box is n/a — say so.
• A rejected or policy-violating prompt, or a provider/rate-limit error, surfaces a clear message in the UI — not a crash, a blank screen, or a silently-broken img. The user can recover and try another prompt.
• Generation is server-side and authorized: the provider API key never reaches the browser (check the network tab / built client bundle — no key, no direct provider call from the page), the generate endpoint requires auth, and a caller cannot run unbounded costly generations through an open or unrate-limited route. Every image is billed.