OpenAI Image & Video Generation API wrapper - DALL-E, GPT Image, and Sora models for Node.js with CLI
npm install openai-image-api



A Node.js wrapper for the OpenAI Image Generation API and OpenAI Video Generation API. Supports DALL-E 2, DALL-E 3, GPT Image 1, and Sora models. Generate, edit, and create variations of images, plus generate and remix videos via CLI or programmatic API.
This service follows the data-collection architecture pattern with organized data storage, logging, parameter validation, and CLI orchestration. Written in TypeScript with full type definitions included.
bash
Install globally
npm install -g openai-image-apiexport OPENAI_API_KEY="your-api-key-here"
Generate an image
openai-img --dalle-3 --prompt "a serene mountain landscape"Generate a video
openai-img --video --sora-2 --prompt "a cat sitting on a windowsill watching the rain" --seconds 4
`$3
`typescript
import { OpenAIImageAPI } from 'openai-image-api';
import { OpenAIVideoAPI } from 'openai-image-api/video-api';const imageApi = new OpenAIImageAPI();
// Generate an image with DALL-E 3
const imageResult = await imageApi.generateImage({
prompt: 'a serene mountain landscape',
model: 'dall-e-3',
quality: 'hd',
size: '1792x1024'
});
console.log('Image URL:', imageResult.data[0].url);
// Generate a video with Sora
const videoApi = new OpenAIVideoAPI();
const videoResult = await videoApi.createVideo({
prompt: 'a cat sitting on a windowsill watching the rain',
model: 'sora-2',
seconds: '4'
});
// Wait for completion
const completedVideo = await videoApi.waitForVideo(videoResult.id);
// Download the video content
const videoBuffer = await videoApi.downloadVideoContent(completedVideo.id);
console.log('Video downloaded:', videoBuffer.length, 'bytes');
`Table of Contents
- Overview
- Models
- Authentication Setup
- Installation
- TypeScript Support
- CLI Usage
- API Methods
- Examples
- Data Organization
- Testing
- Troubleshooting
Overview
This Node.js service implements:
- 6 Generation Models - DALL-E 2, DALL-E 3, GPT Image 1, GPT Image 1.5, Sora 2, Sora 2 Pro
- Image Operations - Generate, Edit, Variation
- Video Operations - Create (text-to-video), Create (image-to-video), List, Retrieve, Delete, Remix
- Parameter Validation - Pre-flight validation catches invalid parameters before API calls
- Security - SSRF protection with DNS rebinding prevention, input validation, rate limiting, log sanitization
- API Key Authentication - Simple Bearer token authentication
- Batch Processing - Generate multiple images sequentially from multiple prompts
- Async Video Polling - Automatic progress tracking with spinner UI and cancellation support
- Organized Storage - Structured directories with timestamped files and metadata
- CLI Orchestration - Command-line tool for batch generation
- Testing - 207 tests with Vitest
Models
$3
Image generation with multiple size options. Supports editing and variations.
Parameters:
-
prompt - Text description of desired image (required for generation)
- size - Image dimensions (256x256, 512x512, 1024x1024)
- n - Number of images to generate (1-10)
- image - Input image for edits/variations (PNG with transparency)
- mask - Mask image for edits (PNG with transparency, edit areas transparent)Features: Generate, edit, variations
$3
Image generation with HD support and style control.
Parameters:
-
prompt - Text description of desired image (required)
- size - Image dimensions (1024x1024, 1792x1024 landscape, 1024x1792 portrait)
- quality - Output quality (standard, hd)
- style - Image style (vivid, natural)
- n - Always 1 (DALL-E 3 only generates one image at a time)Features: HD quality, vivid/natural styles
$3
Image generation with transparency, multi-image editing, and compression control.
Parameters:
-
prompt - Text description of desired image (required)
- size - Image dimensions (1024x1024, 1536x1024, 1024x1536, auto)
- n - Number of images to generate (1-10)
- format - Output format (png, jpeg, webp)
- compression - Compression quality (0-100, for JPEG/WebP)
- transparency - Enable transparent backgrounds (boolean)
- images - Multiple input images for editing (array)
- moderation - Content moderation controlFeatures: Transparent backgrounds, multi-image editing, compression, moderation control
⚠️ IMPORTANT: GPT Image 1 requires a verified organization. See Organization Verification below.
$3
Same capabilities as GPT Image 1, plus partial image streaming support.
Parameters:
-
prompt - Text description of desired image (required)
- size - Image dimensions (1024x1024, 1536x1024, 1024x1536, auto)
- n - Number of images to generate (1-10)
- format - Output format (png, jpeg, webp)
- compression - Compression quality (0-100, for JPEG/WebP)
- transparency - Enable transparent backgrounds (boolean)
- images - Multiple input images for editing (array)
- moderation - Content moderation control
- partial_images - Number of partial images to return during generation (0-3)Features: All GPT Image 1 features, plus partial image streaming
⚠️ IMPORTANT: GPT Image 1.5 requires a verified organization. See Organization Verification below.
$3
Video generation with text-to-video and image-to-video capabilities.
Parameters:
-
prompt - Text description of desired video (required)
- size - Video dimensions (1280x720, 1920x1080, 1080x1920)
- seconds - Video duration: "4", "8", or "12" seconds
- input_reference - Optional reference image for image-to-video generation (PNG, JPEG, WebP)Features: Text-to-video, image-to-video, video remixing, async polling with progress tracking
$3
Video generation with higher quality output.
Parameters:
-
prompt - Text description of desired video (required)
- size - Video dimensions (1280x720, 1920x1080, 1080x1920)
- seconds - Video duration: "4", "8", or "12" seconds
- input_reference - Optional reference image for image-to-video generation (PNG, JPEG, WebP)Features: Enhanced quality, text-to-video, image-to-video, video remixing
Authentication Setup
$3
1. Visit https://platform.openai.com/
2. Create an account or sign in
3. Navigate to API keys section
4. Generate your API key
5. Copy your API key
$3
You can provide your API key in multiple ways (listed in priority order):
#### Option A: CLI Flag (Highest Priority)
`bash
openai-img --api-key YOUR_API_KEY --dalle-3 --prompt "a cat"
`#### Option B: Environment Variable
`bash
Add to your ~/.bashrc, ~/.zshrc, or equivalent
export OPENAI_API_KEY=your_actual_api_key_hereOr use it for a single command
OPENAI_API_KEY=your_key openai-img --dalle-3 --prompt "a cat"
`#### Option C: Local .env File
`bash
In your project directory
echo "OPENAI_API_KEY=your_actual_api_key_here" > .env
`#### Option D: Global Config
`bash
Create config directory
mkdir -p ~/.openaiAdd your API key
echo "OPENAI_API_KEY=your_actual_api_key_here" > ~/.openai/.env
`Security Note: Never commit
.env files or expose your API key publicly.$3
If you want to use the gpt-image-1 model, you must verify your OpenAI organization. Without verification, you'll receive a 400-level error when attempting to use this model.
Verification Process:
1. Go to your OpenAI Organization Settings
2. Navigate to the verification section
3. Complete the KYC (Know Your Customer) process which requires:
- Photo of government-issued ID
- Selfie/photo of yourself
4. Wait for verification approval (typically processed within a few business days)
Why is this required? OpenAI requires organization verification for GPT Image 1 to prevent abuse and ensure responsible use of advanced image generation features like transparent backgrounds and multi-image editing.
Note: DALL-E 2 and DALL-E 3 do NOT require organization verification and can be used immediately with a valid API key.
Installation
$3
`bash
Install globally for CLI usage
npm install -g openai-image-apiOr install locally in your project
npm install openai-image-api
`$3
`bash
Clone the repository
git clone https://github.com/aself101/openai-image-api.git
cd openai-image-apiInstall dependencies
npm install
`Dependencies:
-
axios - HTTP client for API calls
- commander - CLI argument parsing
- dotenv - Environment variable management
- form-data - Multipart form data for file uploads
- winston - Logging framework
- typescript - TypeScript compiler (dev dependency)TypeScript Support
This package is written in TypeScript and includes full type definitions. All types are exported for use in your TypeScript projects.
$3
`typescript
import {
OpenAIImageAPI,
// Type definitions
type GenerateImageParams,
type EditImageParams,
type VariationImageParams,
type ImageResponse,
type ImageModel,
type APIOptions
} from 'openai-image-api';import {
OpenAIVideoAPI,
type CreateVideoParams,
type VideoObject,
type ListVideosResponse,
type VideoModel,
type PollVideoOptions
} from 'openai-image-api/video-api';
`$3
`
openai-api/
├── src/ # TypeScript source files
│ ├── api.ts # Image API class
│ ├── video-api.ts # Video API class
│ ├── config.ts # Configuration & validation
│ ├── utils.ts # Utility functions
│ ├── cli.ts # CLI entry point
│ └── types.ts # Type definitions
├── dist/ # Compiled JavaScript (generated)
├── test/ # Test files (TypeScript)
└── tsconfig.json # TypeScript configuration
`$3
`bash
Install dependencies
npm installBuild TypeScript to JavaScript
npm run buildWatch mode for development
npm run build:watch
`Quick Start
$3
The CLI command depends on how you installed the package:
If installed globally (
npm install -g openai-image-api):
`bash
openai-img --examples # Show usage examples
openai-img --dalle-3 --prompt "a cat" # Generate with DALL-E 3
`If installed locally in a project:
`bash
npx openai-img --examples # Show usage examples
npx openai-img --dalle-3 --prompt "a cat" # Generate with DALL-E 3
`If working from source (cloned repository):
`bash
npm run openai:examples # Show usage examples
npm run openai -- --dalle-3 --prompt "a cat" # Generate
`$3
`bash
Show examples
openai-img --examplesGenerate with DALL-E 3
openai-img --dalle-3 --prompt "a serene mountain landscape"Generate with GPT Image 1 (transparent background)
openai-img --gpt-image-1 --prompt "a cute robot" --background transparentEdit image with DALL-E 2
openai-img --dalle-2 --edit --image photo.png --prompt "add snow"Batch generation
openai-img --dalle-3 \
--prompt "a cat" \
--prompt "a dog" \
--prompt "a bird"
`Note: Examples below use
openai-img directly (global install). If using local install, prefix with npx: npx openai-img --dalle-3 ...$3
`typescript
// If installed via npm
import { OpenAIImageAPI } from 'openai-image-api';// If running from source
import { OpenAIImageAPI } from './dist/api.js';
// Initialize the API
const api = new OpenAIImageAPI();
// Generate with DALL-E 3
const result = await api.generateImage({
prompt: 'a beautiful sunset',
model: 'dall-e-3',
size: '1024x1024',
quality: 'hd',
style: 'vivid'
});
console.log('Generated images:', result.data);
`CLI Usage
$3
`bash
Global install
openai-img [model] [options]Local install (use npx)
npx openai-img [model] [options]From source (development)
npm run openai -- [model] [options]
`$3
Choose one model:
Image Models:
`bash
--dalle-2 # DALL-E 2
--dalle-3 # DALL-E 3
--gpt-image-1 # GPT Image 1
--gpt-image-15 # GPT Image 1.5 (adds partial image streaming)
`Video Models:
`bash
--video --sora-2 # Sora 2
--video --sora-2-pro # Sora 2 Pro
`$3
Image Operations:
`bash
Default: generate new image
--edit # Edit existing image(s)
--variation # Create variations of image
`Video Operations:
`bash
--video # Enable video mode (required for video generation)
--list-videos # List all videos
--delete-video # Delete a video by ID
--remix-video # Remix an existing video
`$3
Image Options:
`bash
--prompt # Prompt (can specify multiple for batch)
--image # Input image (required for edit/variation)
--mask # Mask image for editing
--size # Image size (e.g., 1024x1024)
--quality # Image quality
--n # Number of images to generate
--response-format # url or b64_json (dalle-2/3 only)
--output-dir # Custom output directory
--log-level # DEBUG, INFO, WARNING, ERROR
--dry-run # Preview without API call
--examples # Show usage examples
`Video Options:
`bash
--prompt # Video description (required for generation)
--input-reference # Reference image for image-to-video
--size # Video dimensions (1280x720, 1920x1080, 1080x1920)
--seconds # Video duration ("4", "8", or "12")
--list-videos # List all videos
--delete-video # Delete a video by ID
--remix-video # Remix an existing video with new prompt
--output-dir # Custom output directory
--log-level # DEBUG, INFO, WARNING, ERROR
`$3
`bash
--style