interface PollinationsConfig { /** API key for authentication (get one at https://enter.pollinations.ai) */ apiKey?: string; /** Base URL for the API (defaults to https://gen.pollinations.ai) */ baseUrl?: string; /** Maximum number of retry attempts (default: 3) */ maxRetries?: number; /** Default timeout in ms for all requests (default: 300000 = 5min) */ timeout?: number; /** Timeout in ms for text requests (default: 300000 = 5min) */ textTimeout?: number; /** Timeout in ms for image requests (default: 600000 = 10min) */ imageTimeout?: number; /** Timeout in ms for video requests (default: 600000 = 10min) */ videoTimeout?: number; } /** Common options for all request methods */ interface RequestOptions { /** AbortSignal for request cancellation */ signal?: AbortSignal; } /** Image model (use getImageModels() to fetch available models) */ type ImageModel = string; /** Available video models */ type VideoModel = string; /** Image quality options */ type ImageQuality = "low" | "medium" | "high" | "hd"; /** Reasoning depth for supported image models */ type ImageReasoningMode = "fast" | "balanced" | "pro"; /** Options for image generation */ interface ImageGenerateOptions extends RequestOptions { /** Image model to use (default: 'zimage') */ model?: ImageModel; /** Image width in pixels (default: 1024) */ width?: number; /** Image height in pixels (default: 1024) */ height?: number; /** Seed for reproducible generation (default: random) */ seed?: number; /** Let AI enhance/improve your prompt (default: false) */ enhance?: boolean; /** Negative prompt - what to avoid in the image */ negativePrompt?: string; /** Keep generation private (default: false) */ private?: boolean; /** Remove watermark logo (default: false) */ nologo?: boolean; /** Don't show in public feed (default: false) */ nofeed?: boolean; /** Enable safety content filters (default: false) */ safe?: boolean; /** Output quality (default: 'medium') */ quality?: ImageQuality; /** Reference image URL(s) for image-to-image generation */ referenceImage?: string | string[]; /** Enable transparent background - outputs PNG (default: false) */ transparent?: boolean; /** How closely to follow prompt, 1-20 (higher = stricter) */ guidanceScale?: number; /** * Reasoning mode for supported image models. * Booleans are accepted for backward compatibility: true = "pro", * false = "balanced". */ reasoning?: boolean | ImageReasoningMode; } /** Options for image editing (POST /v1/images/edits) */ interface ImageEditOptions extends RequestOptions { /** Image model to use (default: 'flux') */ model?: ImageModel; /** Source image URL(s) for editing */ image?: string | string[]; } /** Response from image generation */ interface ImageResponse { /** The generated image as a Buffer (Node.js) or ArrayBuffer (browser) */ buffer: ArrayBuffer; /** Content type (image/jpeg or image/png) */ contentType: string; /** The URL that was used to generate the image */ url: string; } /** Options for video generation */ interface VideoGenerateOptions extends RequestOptions { /** Video model to use (default: 'veo') */ model?: VideoModel; /** Duration in seconds (1-30, varies by model) */ duration?: number; /** Aspect ratio (e.g., '16:9', '9:16', '1:1') */ aspectRatio?: string; /** Seed for reproducible generation */ seed?: number; /** Enable audio generation where supported by the selected video model */ audio?: boolean; /** Reference image URL(s) for image-to-video. For video, image[0] is the start frame and image[1] is the end frame when supported. */ referenceImage?: string | string[]; /** Keep generation private (default: false) */ private?: boolean; /** Remove watermark logo (default: false) */ nologo?: boolean; /** Enable safety content filters (default: false) */ safe?: boolean; } /** Response from video generation */ interface VideoResponse { /** The generated video as a Buffer (Node.js) or ArrayBuffer (browser) */ buffer: ArrayBuffer; /** Content type (video/mp4) */ contentType: string; /** The URL that was used to generate the video */ url: string; } /** Text model (use getTextModels() to fetch available models) */ type TextModel = string; /** Message roles for chat */ type MessageRole = "system" | "developer" | "user" | "assistant" | "tool" | "function"; /** Text content part */ interface TextContentPart { type: "text"; text: string; } /** Image content part for vision */ interface ImageContentPart { type: "image_url"; image_url: { url: string; detail?: "auto" | "low" | "high"; mime_type?: string; }; } /** Video content part */ interface VideoContentPart { type: "video_url"; video_url: { url: string; mime_type?: string; }; } /** Audio content part */ interface AudioContentPart { type: "input_audio"; input_audio: { /** Base64 encoded audio data */ data: string; format: "wav" | "mp3" | "flac" | "opus" | "pcm16"; }; } /** File content part */ interface FileContentPart { type: "file"; file: { file_data?: string; file_id?: string; file_name?: string; file_url?: string; mime_type?: string; }; } /** All possible content parts */ type MessageContentPart = TextContentPart | ImageContentPart | VideoContentPart | AudioContentPart | FileContentPart; /** Message content - either a string or array of content parts */ type MessageContent = string | MessageContentPart[]; /** A chat message */ interface Message { role: MessageRole; content: MessageContent; name?: string; /** For tool messages */ tool_call_id?: string; } /** Options for simple text generation */ interface TextGenerateOptions extends RequestOptions { /** Text model to use (default: 'openai') */ model?: TextModel; /** System prompt to set context */ systemPrompt?: string; /** Seed for reproducible generation */ seed?: number; /** Return response as JSON (default: false) */ json?: boolean; /** Temperature 0-2, higher = more creative (default: 1) */ temperature?: number; /** Maximum tokens to generate */ maxTokens?: number; /** Frequency penalty -2 to 2 */ frequencyPenalty?: number; /** Presence penalty -2 to 2 */ presencePenalty?: number; /** Enable streaming response (default: false) */ stream?: boolean; /** Keep generation private (default: false) */ private?: boolean; } /** Response format options */ type ResponseFormat = { type: "text"; } | { type: "json_object"; } | { type: "json_schema"; json_schema: JsonSchema; }; /** JSON schema for structured output */ interface JsonSchema { name: string; description?: string; schema: Record; strict?: boolean; } /** Tool definition */ interface Tool { type: "function"; function: { name: string; description?: string; parameters?: Record; strict?: boolean; }; } /** Built-in tool types */ type BuiltInToolType = "code_execution" | "google_search" | "google_maps" | "url_context" | "computer_use" | "file_search"; /** Thinking/reasoning options */ interface ThinkingOptions { type: "enabled" | "disabled"; budget_tokens?: number; } /** Options for chat completions (POST endpoint) */ interface ChatOptions extends RequestOptions { /** Text model to use (default: 'openai') */ model?: TextModel; /** Temperature 0-2 (default: 1) */ temperature?: number; /** Top P sampling 0-1 (default: 1) */ topP?: number; /** Maximum tokens to generate */ maxTokens?: number; /** Frequency penalty -2 to 2 */ frequencyPenalty?: number; /** Presence penalty -2 to 2 */ presencePenalty?: number; /** Repetition penalty */ repetitionPenalty?: number; /** Stop sequences (max 4) */ stop?: string | string[]; /** Seed for reproducible generation */ seed?: number; /** Enable streaming response (default: false) */ stream?: boolean; /** Include usage stats in streaming response */ streamOptions?: { include_usage?: boolean; }; /** Response format */ responseFormat?: ResponseFormat; /** Tools available to the model */ tools?: (Tool | { type: BuiltInToolType; })[]; /** Tool choice: 'none', 'auto', 'required', or specific function */ toolChoice?: "none" | "auto" | "required" | { type: "function"; function: { name: string; }; }; /** Allow parallel tool calls (default: true) */ parallelToolCalls?: boolean; /** Enable thinking/reasoning for supported models */ thinking?: ThinkingOptions | null; /** Reasoning effort for thinking models */ reasoningEffort?: "low" | "medium" | "high"; /** Thinking budget in tokens */ thinkingBudget?: number; /** Output modalities */ modalities?: ("text" | "audio")[]; /** Audio output options */ audio?: { voice?: AudioVoice; format?: AudioFormat; }; /** User identifier for tracking */ user?: string; /** Logit bias for token probabilities */ logitBias?: Record; /** Return log probabilities */ logprobs?: boolean; /** Number of top log probabilities to return (0-20) */ topLogprobs?: number; /** Legacy function calling (use tools instead) */ functions?: FunctionDefinition[]; /** Legacy function call control (use toolChoice instead) */ functionCall?: "none" | "auto" | { name: string; }; } /** Legacy function definition (use Tool instead) */ interface FunctionDefinition { name: string; description?: string; parameters?: Record; } /** A tool call in the response */ interface ToolCall { id: string; type: "function"; function: { name: string; arguments: string; }; } /** Token usage information */ interface CompletionUsage { prompt_tokens: number; completion_tokens: number; total_tokens: number; prompt_tokens_details?: { cached_tokens?: number; audio_tokens?: number; }; completion_tokens_details?: { reasoning_tokens?: number; audio_tokens?: number; }; } /** A choice in the chat response */ interface ChatChoice { index: number; message: { role: "assistant"; content: string | null; tool_calls?: ToolCall[]; audio?: { transcript: string; data: string; id: string; expires_at: number; } | null; reasoning_content?: string | null; }; finish_reason: "stop" | "length" | "tool_calls" | "content_filter" | null; logprobs?: { content?: Array<{ token: string; logprob: number; bytes?: number[]; top_logprobs?: Array<{ token: string; logprob: number; bytes?: number[]; }>; }>; } | null; } /** Chat completion response */ interface ChatResponse { id: string; object: "chat.completion"; created: number; model: string; choices: ChatChoice[]; usage?: CompletionUsage; system_fingerprint?: string; citations?: string[]; } /** A chunk in streaming response */ interface ChatStreamChunk { id: string; object: "chat.completion.chunk"; created: number; model: string; choices: Array<{ index: number; delta: { role?: "assistant"; content?: string; tool_calls?: Array<{ index: number; id?: string; type?: "function"; function?: { name?: string; arguments?: string; }; }>; }; finish_reason: "stop" | "length" | "tool_calls" | "content_filter" | null; }>; usage?: CompletionUsage; } /** Voice option for audio generation */ type AudioVoice = string; /** Audio format options */ type AudioFormat = "wav" | "mp3" | "flac" | "opus" | "pcm16"; /** Dedicated audio/music model */ type AudioModel = "elevenlabs" | "elevenmusic" | "acestep" | string; /** Options for text-to-speech generation (GET /audio/{text} or POST /v1/audio/speech) */ interface AudioGenerateOptions extends RequestOptions { /** Voice to use (default: 'alloy') */ voice?: AudioVoice; /** Audio model to use (default: 'elevenlabs') */ model?: AudioModel; /** Duration in seconds (for music models like elevenmusic, acestep) */ duration?: number; /** Seed for reproducibility */ seed?: number; } /** Response from dedicated audio endpoints (binary audio data) */ interface AudioBinaryResponse { /** The generated audio as a Buffer (Node.js) or ArrayBuffer (browser) */ buffer: ArrayBuffer; /** Content type (audio/mpeg) */ contentType: string; } /** Audio response from chat with audio modality */ interface AudioResponse { /** Transcript of the audio */ transcript: string; /** Base64 encoded audio data */ data: string; /** Audio ID */ id: string; /** Expiration timestamp */ expiresAt: number; } /** STT model options */ type TranscriptionModel = "whisper-large-v3" | "whisper-1" | "scribe" | "universal-2" | "universal-3-pro" | string; /** Response format for transcription */ type TranscriptionResponseFormat = "json" | "text" | "verbose_json" | "srt" | "vtt"; /** Options for speech-to-text transcription */ interface TranscribeOptions extends RequestOptions { /** Model to use (default: 'whisper-large-v3') */ model?: TranscriptionModel; /** Language code (ISO-639-1, e.g. 'en', 'fr') */ language?: string; /** Response format (default: 'json') */ responseFormat?: TranscriptionResponseFormat; /** Optional prompt to guide transcription style */ prompt?: string; /** Temperature 0-1 for sampling */ temperature?: number; } /** Transcription response */ interface TranscriptionResponse { /** Transcribed text */ text: string; } /** Verbose transcription response with word/segment details */ interface TranscriptionVerboseResponse extends TranscriptionResponse { task: string; language: string; duration: number; words?: Array<{ word: string; start: number; end: number; }>; segments?: Array<{ id: number; start: number; end: number; text: string; }>; } /** Options for media upload */ interface UploadOptions extends RequestOptions { /** Original filename (optional) */ name?: string; /** Content type (auto-detected if omitted) */ contentType?: string; } /** Response from media upload */ interface UploadResponse { /** Content-addressed hash ID */ id: string; /** Public URL for the uploaded media */ url: string; /** Content type of the uploaded file */ contentType: string; /** File size in bytes */ size: number; /** Whether the file was already uploaded (dedup) */ duplicate: boolean; } /** Account permission scopes */ type AccountPermission = "profile" | "usage" | "keys"; /** Options for building a BYOP authorization URL */ interface AuthorizeOptions { /** URL to redirect back to after authorization */ redirectUrl: string; /** Your app's publishable key (shows app name to user) */ appKey?: string; /** OAuth state value echoed back to the redirect URL */ state?: string; /** Authorization host (defaults to https://enter.pollinations.ai) */ authBaseUrl?: string; /** Restrict to specific models */ models?: string[]; /** Numeric pollen cap. Omit for the default cap. */ budget?: number; /** Key lifetime in days (default: 30) */ expiry?: number; /** Account permissions to request */ permissions?: AccountPermission[]; } /** User profile information */ interface AccountProfile { githubUsername: string | null; image: string | null; /** Current tier level (e.g. `"spore"`, `"seed"`, `"flower"`, `"nectar"`). */ tier: string; /** ISO 8601 timestamp of the next pollen refill. `null` for tiers with no refill. */ nextResetAt: string | null; /** Only returned when the API key has the `profile` permission */ name?: string | null; /** Only returned when the API key has the `profile` permission */ email?: string | null; } /** Account balance */ interface AccountBalance { balance: number; } /** Usage record */ interface UsageRecord { timestamp: string; type: string; model: string; api_key: string; api_key_type: string; meter_source: string; input_text_tokens: number; input_cached_tokens: number; input_audio_tokens: number; input_audio_seconds: number; input_image_tokens: number; output_text_tokens: number; output_reasoning_tokens: number; output_audio_tokens: number; output_audio_seconds: number; output_image_tokens: number; output_video_seconds: number; cost_usd: number; response_time_ms: number; } /** Usage response */ interface UsageResponse { usage: UsageRecord[]; count: number; } /** Options for fetching usage */ interface UsageOptions { /** Response format (default: 'json') */ format?: "json" | "csv"; /** Number of days to include, max 90 (default: 30) */ days?: number; /** Max records to return, 1-50000 (default: 100). CSV exports are capped at 50000. */ limit?: number; /** ISO timestamp cursor for pagination */ before?: string; /** Exact period granularity */ granularity?: "day" | "week" | "month"; /** Exact period, e.g. YYYY-MM-DD, YYYY-WNN, or YYYY-MM */ period?: string; } /** Options for fetching current-key usage. CSV export is not supported here. */ type KeyUsageOptions = Omit; /** Options for fetching daily usage */ interface DailyUsageOptions { /** Response format (default: 'json') */ format?: "json" | "csv"; /** Number of days to include, max 90 (default: 90) */ days?: number; /** Exact period granularity */ granularity?: "day" | "week" | "month"; /** Exact period, e.g. YYYY-MM-DD, YYYY-WNN, or YYYY-MM */ period?: string; /** Filter to one or more API keys by id */ api_key_ids?: string[]; } /** Daily usage summary */ interface DailyUsageRecord { date: string; model: string; meter_source: string; requests: number; cost_usd: number; } /** Daily usage response */ interface DailyUsageResponse { usage: DailyUsageRecord[]; count: number; } /** API key validation response */ interface KeyInfo { valid: boolean; type: string; name?: string | null; expiresAt?: string | null; expiresIn?: number | null; permissions?: { models?: string[] | null; account?: string[] | null; }; pollenBudget?: number | null; rateLimitEnabled?: boolean; } /** Detailed key record returned by GET /account/keys (list) */ interface AccountKey { id: string; name: string; /** First few characters of the key (for identification) */ start?: string; prefix: string; type?: string; createdAt: string; expiresAt: string | null; lastRequest: string | null; permissions: { tier?: string[]; models?: string[]; account?: string[]; } | null; metadata: Record | null; pollenBalance: number | null; enabled: boolean; } /** Key-scope permissions that can be granted on created keys. */ type KeyAccountPermission = "profile" | "usage" | "keys" | string; /** Options for POST /account/keys */ interface CreateKeyOptions { /** Human-readable name */ name: string; /** Key type (default: "secret") */ type?: "secret" | "publishable"; /** Expiry in seconds from creation */ expiresIn?: number; /** Restrict to specific model IDs */ allowedModels?: string[]; /** Pollen budget cap */ pollenBudget?: number; /** * Account permissions to grant (e.g. `["profile", "usage"]`). * Without this, scoped keys cannot read account state beyond their * own key metadata, budget, and per-key usage. * `"keys"` is auto-stripped server-side on the BYOP flow. */ accountPermissions?: KeyAccountPermission[]; /** * Allowed OAuth redirect URIs for publishable app keys. Required when * creating a `publishable` key that drives the `/authorize` BYOP flow. * Matching pins scheme, host, port, and path; one trailing slash is * ignored; loopback ports are matched port-agnostically. */ redirectUris?: string[]; /** * Opt the publishable app key into developer earnings. Defaults to * `false` server-side; only meaningful on `type: "publishable"` keys. */ earningsEnabled?: boolean; } /** * Response from POST /account/keys — includes the raw `key` value which * is ONLY shown at creation time. Store it immediately. */ interface CreatedKey { id: string; /** The secret key value. Only returned once at creation. */ key: string; name: string; type: string; prefix: string; expiresAt: string | null; permissions: { models?: string[]; account?: string[]; } | null; pollenBudget: number | null; } /** Model tier levels */ type ModelTier = "anonymous" | "seed" | "flower" | "nectar"; /** Per-model video frame-control capabilities (video models only) */ type VideoCapability = "start_frame" | "end_frame" | "keyframes" | "audio_output"; /** Model information */ interface ModelInfo { name: string; description?: string; aliases?: string[]; tier?: ModelTier; community?: boolean; input_modalities?: string[]; output_modalities?: string[]; video_capabilities?: VideoCapability[]; tools?: boolean; vision?: boolean; audio?: boolean; reasoning?: boolean; uncensored?: boolean; voices?: string[]; maxInputChars?: number; context_length?: number; supportsSystemMessages?: boolean; is_specialized?: boolean; pricing?: { currency: "pollen"; input_token_price?: number; output_token_price?: number; cached_token_price?: number; image_price?: number; audio_input_price?: number; audio_output_price?: number; }; } /** Raw response from POST /api/device/code */ interface DeviceCodeResponse { device_code: string; user_code: string; verification_uri_complete: string; expires_in: number; interval: number; } /** Raw response from POST /api/device/token (polling) */ interface DeviceTokenResponse { access_token?: string; error?: string; error_description?: string; } /** Options for starting device flow */ interface AuthorizeDeviceOptions extends RequestOptions { /** OAuth client ID. Defaults to the public polli CLI client. */ clientId?: string; /** Space-separated scope string (default: "generate keys usage") */ scope?: string; } /** * Handle returned by `authorizeDevice()` — surfaces the user-facing * verification URL/code, and exposes `poll()` to block until approval. */ interface DeviceAuthorization { /** Short code the user types in the verification page */ userCode: string; /** URL to open in a browser (includes the user code as a query param) */ verificationUri: string; /** When the device code expires and polling must stop */ expiresAt: Date; /** Block until the user approves. Resolves with an access token or throws. */ poll(): Promise; } /** User identity returned by GET /api/device/userinfo */ interface UserInfo { sub?: string; name?: string; email?: string; githubUsername?: string; tier?: string; [key: string]: unknown; } /** Options for POST /v1/images/generations */ interface ImageGenerateV1Options extends RequestOptions { /** Image model to use (default: 'zimage') */ model?: ImageModel; /** Size string like "1024x1024". Alternative to width + height. */ size?: string; /** Image width in pixels (converted to `size` when both dimensions provided) */ width?: number; /** Image height in pixels */ height?: number; /** Number of images to generate (default: 1) */ n?: number; /** Response format (default: server decides — usually b64_json) */ responseFormat?: "url" | "b64_json"; /** Reasoning mode for supported image models. Booleans are accepted for backward compatibility. */ reasoning?: boolean | ImageReasoningMode; /** Seed for reproducible generation */ seed?: number; /** Output quality */ quality?: ImageQuality; /** Negative prompt - what to avoid */ negativePrompt?: string; } /** API error details */ interface PollinationsErrorDetails { code: "BAD_REQUEST" | "UNAUTHORIZED" | "INSUFFICIENT_BALANCE" | "PERMISSION_DENIED" | "INTERNAL_ERROR" | string; message: string; timestamp: string; details?: Record; requestId?: string; } /** Pollinations SDK Error */ declare class PollinationsError extends Error { code: string; status: number; details?: Record; requestId?: string; /** Retry-After value in seconds (for 429 rate limit errors) */ retryAfter?: number; constructor(message: string, code: string, status: number, details?: Record, requestId?: string, retryAfter?: number); } export { type JsonSchema as $, type AudioGenerateOptions as A, type AudioContentPart as B, type ChatOptions as C, type DeviceAuthorization as D, type AudioFormat as E, type AudioModel as F, type AudioResponse as G, type AudioVoice as H, type ImageGenerateOptions as I, type BuiltInToolType as J, type KeyInfo as K, type ChatChoice as L, type Message as M, type CompletionUsage as N, type DailyUsageRecord as O, type PollinationsConfig as P, type DeviceCodeResponse as Q, type RequestOptions as R, type DeviceTokenResponse as S, type TextGenerateOptions as T, type UploadOptions as U, type VideoGenerateOptions as V, type FileContentPart as W, type FunctionDefinition as X, type ImageContentPart as Y, type ImageModel as Z, type ImageQuality as _, type ImageResponse as a, type KeyAccountPermission as a0, type MessageContent as a1, type MessageContentPart as a2, type MessageRole as a3, type ModelTier as a4, PollinationsError as a5, type PollinationsErrorDetails as a6, type ResponseFormat as a7, type TextContentPart as a8, type TextModel as a9, type ThinkingOptions as aa, type Tool as ab, type ToolCall as ac, type TranscriptionModel as ad, type TranscriptionResponseFormat as ae, type UsageRecord as af, type VideoContentPart as ag, type VideoModel as ah, type ImageEditOptions as b, type ImageGenerateV1Options as c, type VideoResponse as d, type ChatResponse as e, type ChatStreamChunk as f, type AudioBinaryResponse as g, type ModelInfo as h, type TranscribeOptions as i, type TranscriptionVerboseResponse as j, type TranscriptionResponse as k, type UploadResponse as l, type AuthorizeOptions as m, type AuthorizeDeviceOptions as n, type UserInfo as o, type AccountProfile as p, type AccountBalance as q, type UsageOptions as r, type UsageResponse as s, type DailyUsageOptions as t, type DailyUsageResponse as u, type KeyUsageOptions as v, type AccountKey as w, type CreateKeyOptions as x, type CreatedKey as y, type AccountPermission as z };