OpenAI Image & Video Generation Service


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.

Quick Start

$3

``bash

Install globally

npm install -g openai-image-api

export 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 control

Features: 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_here

Or 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 ~/.openai

Add 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-api

Or 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-api

Install 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 install

Build TypeScript to JavaScript

npm run build

Watch 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 --examples

Generate 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 transparent

Edit 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