A comprehensive collection of TypeScript/Node.js CLI projects demonstrating various OpenAI API capabilities. This lab covers text generation, embeddings, image generation, audio processing, video analysis, and AI agent tools.
Author: Aymane Mehdi
Repository: github.com/AymaneMehdi/OpenAI-Node.js-CLI-TS-Lab
This lab contains 10 progressive projects that demonstrate different aspects of the OpenAI API:
| # | Project | Purpose | Features |
|---|---|---|---|
| 01 | Basic Text | Introduction to text generation | Simple API call |
| 02 | Text CLI | Single question interface | User input from terminal |
| 03 | Text CLI Loop | Interactive chat interface | Multi-turn conversation |
| 04 | System Instructions | Role-based AI behavior | Custom system prompts |
| 05 | JSON Output | Structured data extraction | JSON formatting |
| 06 | Tools Agent | Function calling capability | AI tool selection |
| 07 | Embeddings | Vector embeddings & similarity | Semantic search |
| 08 | Image | Text-to-image generation | Image creation & saving |
| 09 | Audio | Text-to-speech synthesis | MP3 generation |
| 10 | Video | Video analysis & understanding | Video processing |
- Node.js 18+ installed
- OpenAI API key (Get one here)
-
Clone or download the project
cd OpenAI-Node.js-CLI-TS-Lab -
Install dependencies
npm install
-
Set up environment variables Create a
.envfile in the project root:OPENAI_API_KEY=your_api_key_here -
Compile TypeScript (if needed)
npx tsc
-
Run any project
npx ts-node 01-basic-text.ts npx ts-node 02-text-cli.ts npx ts-node 03-text-cli-loop.ts npx ts-node 04-system-instructions.ts npx ts-node 05-json-output.ts npx ts-node 06-tools-agent.ts npx ts-node 07-embeddings.ts npx ts-node 08-image.ts npx ts-node 09-audio.ts npx ts-node 10-video.ts
What it does: Sends a simple request to OpenAI's GPT-5.5 model and displays the response.
Use case: Learn the basic structure of making API calls to OpenAI.
Features:
- Simple one-shot API call
- Hardcoded prompt
- Prints AI response to console
Example:
npx ts-node 01-basic-text.tsOutput: Explanation of what an LLM is for JavaScript developers.
What it does: Creates an interactive terminal interface where you ask a single question and get an AI response.
Use case: Basic user interaction with the AI through the command line.
Features:
- Uses
readlinefor terminal input - Reads OpenAI API key from
.env - Single question-answer interaction
- CLI closes after one answer
Example:
npx ts-node 02-text-cli.tsInput: You'll be prompted to enter a question
Ask AI: What is JavaScript?
Output: AI explanation displayed in console.
What it does: Creates a multi-turn chat interface where you can ask multiple questions continuously.
Use case: Build a simple chatbot with conversation history potential.
Features:
- Continuous chat loop (type 'exit' to quit)
- Reads each user input
- Displays AI responses
- Error handling
Example:
npx ts-node 03-text-cli-loop.tsInteraction:
OpenAI CLI Chat
Type your question. Type 'exit' to quit.
You: What is React?
AI: React is a JavaScript library...
You: How does it work?
AI: React works by managing state...
You: exit
Goodbye!
What it does: Demonstrates system instructions by making the AI act as a specific expert (JavaScript/React coach).
Use case: Control AI behavior and create specialized assistants with specific personalities.
Features:
- System instructions to define AI role
- Interactive chat loop with custom behavior
- AI acts as a "senior JavaScript and React coach"
- Simplified explanations with examples
- Exit command support
Example:
npx ts-node 04-system-instructions.tsInteraction:
AI Role Assistant
Type your question. Type 'exit' to quit.
You: Explain destructuring
AI: Destructuring is like unpacking a box... [coach explains simply]
Key Point: The instructions parameter controls how the AI behaves.
What it does: Forces the AI to return responses in a specific JSON structure instead of plain text.
Use case: Extract structured data from AI responses for programmatic use.
Features:
- System instructions to ensure JSON output
- Defined JSON schema in prompt
- Structured data with title, level, summary, example
- Useful for databases and APIs
Example:
npx ts-node 05-json-output.tsInput Prompt:
You: Explain React useState
Expected JSON output:
{
"title": "React useState Hook",
"level": "intermediate",
"summary": "useState allows functional components to have state",
"example": "const [count, setCount] = useState(0);"
}
Use Case: Parse the response and use it in your application.
What it does: Teaches AI to call specific functions/tools defined by you. The AI recognizes when to use a tool and what parameters to pass.
Use case: Build AI agents that can take actions (call functions, APIs, databases).
Features:
- Defines available tools using JSON schema
getWeather()function as example tool- AI can ask to use the tool with correct parameters
- Demonstrates AI reasoning about when/how to use tools
Example Function:
function getWeather({ city }: { city: string }): string {
return `The weather in ${city} is 25°C and clear.`;
}Tool Schema: Describes tool name, description, and parameters.
Example:
npx ts-node 06-tools-agent.tsInteraction:
You: What's the weather in Casablanca?
AI: [Recognizes getWeather tool is needed]
AI: [Calls getWeather with city="Casablanca"]
AI: The weather in Casablanca is 25°C and clear.
What it does: Converts text documents to vector embeddings and finds the most relevant document for a query using cosine similarity.
Use case: Implement semantic search, RAG (Retrieval Augmented Generation), or recommendation systems.
Features:
- Converts documents to embeddings using
text-embedding-3-smallmodel - Calculates cosine similarity between vectors
- Finds best matching document for a query
- In-memory document database (extensible to MongoDB, Supabase, etc.)
Example Documents:
- "React is a JavaScript library for building user interfaces."
- "Next.js is a React framework that supports server-side rendering."
- "MongoDB is a NoSQL database used to store data."
Query: "What is SSR in Next.js?"
Process:
- Query → Convert to embedding
- Compare to all document embeddings
- Return best match: "Next.js is a React framework that supports server-side rendering."
Use Cases:
- Build search engines
- Implement Retrieval Augmented Generation (RAG)
- Semantic similarity matching
What it does: Takes a text prompt and generates an AI image using OpenAI's image model, then saves it locally as PNG.
Use case: Generate images programmatically without design skills.
Features:
- Interactive prompt input
- Generates 1024x1024 images
- Converts base64 response to image file
- Saves as
generated-image.png - File system integration
Example:
npx ts-node 08-image.tsInteraction:
AI Image Generator
Example: A futuristic JavaScript robot coding at night
Image prompt: A serene mountain landscape at sunset
Output:
Image saved as generated-image.png
Use Cases:
- Generate marketing images
- Create UI mockups
- Generate art programmatically
- Build image-based applications
What it does: Converts text input into speech audio and saves it as an MP3 file.
Use case: Add voice to applications, create audiobooks, generate voice messages.
Features:
- Text input from user
- Converts text to audio using
gpt-4o-mini-ttsmodel - Voice selection (
coralvoice) - Custom instructions for tone (friendly, clear)
- Saves as
speech.mp3 - Uses async file system operations
Example:
npx ts-node 09-audio.tsInteraction:
AI Text To Speech App
Type text and AI will generate an MP3 file.
Text: Hello, this is an AI voice speaking to you!
Output:
Audio saved as speech.mp3
Use Cases:
- Accessibility features
- Audiobook generation
- Voice notifications
- Interactive applications with audio feedback
What it does: Analyzes video files by converting them to base64 and sending them to OpenAI for understanding and description.
Use case: Extract information from videos, generate descriptions, analyze video content.
Features:
- File path input from user
- Reads video file from disk
- Converts video to base64 encoding
- Sends to OpenAI for analysis
- Supports video analysis in API request
Example:
npx ts-node 10-video.tsInteraction:
AI Video Analysis App
Provide path to a video file
Video path: ./my-video.mp4
Output: AI description of video content.
Use Cases:
- Video transcription
- Content analysis
- Automated video description
- Video content moderation
- Generate metadata for video libraries
{
"openai": "^6.35.0",
"env": "^0.0.2"
}- readline/promises - Terminal input/output (CLI interaction)
- fs - File system operations (reading/writing images, videos, audio)
- fs/promises - Async file operations
gpt-5.5- Main text generation modeltext-embedding-3-small- Vector embeddingsgpt-image-2- Image generationgpt-4o-mini-tts- Text-to-speech- Models for video analysis
- Start with 01-basic-text.ts - Understand basic API calls
- Move to 02-text-cli.ts - Learn user interaction
- Try 03-text-cli-loop.ts - Build conversational AI
- Explore 04-system-instructions.ts - Control AI behavior
- Study 05-json-output.ts - Get structured data
- Learn 06-tools-agent.ts - AI function calling
- Master 07-embeddings.ts - Vector search & RAG
- Implement 08-image.ts - Image generation
- Integrate 09-audio.ts - Audio capabilities
- Deploy 10-video.ts - Video analysis
- Chatbots: Use projects 03, 04 as foundation
- Search Engine: Build on project 07 (embeddings)
- TypeScript Support: All projects are written in TypeScript with full type safety
- Content Generation: Combine projects 08, 09 for multimedia
- AI Agents: Start with project 06 (tools/function calling)
- RAG System: Use project 07 with external knowledge base
- All projects require a valid OpenAI API key
- API calls consume credits - monitor your usage
- Modify prompts and parameters to customize AI behavior
- Extend projects by saving outputs to databases
- Combine multiple projects for complex applications
This project is licensed under the MIT License.
Copyright© Aymane Mehdi