@embedapi/core

EmbedAPI Client

A Node.js client for interacting with the EmbedAPI service.

🔥 ONE API KEY TO RULE THEM ALL! Access ANY AI model instantly through our game-changing unified API. Build AI apps in minutes, not months! The ultimate all-in-one AI agent solution you've been waiting for! 🚀

Visit embedapi.com to get your API key and start building!

Installation

npm install @embedapi/core

Using yarn:

yarn add @embedapi/core

Using pnpm:

pnpm add @embedapi/core

Initialization

const EmbedAPIClient = require('@embedapi/core');

# Regular API client
const client = new EmbedAPIClient('your-api-key');

# Agent mode client
const agentClient = new EmbedAPIClient('your-agent-id', { isAgent: true });

# Debug mode client
const debugClient = new EmbedAPIClient('your-api-key', { debug: true });

# Agent and debug mode client
const debugAgentClient = new EmbedAPIClient('your-agent-id', { 
    isAgent: true, 
    debug: true 
});

Constructor Parameters

• apiKey (string): Your API key for regular mode, or agent ID for agent mode
• options (object, optional): Configuration options
  • isAgent (boolean, optional): Set to true to use agent mode. Defaults to false
  • debug (boolean, optional): Set to true to enable debug logging. Defaults to false

Methods

1. generate(options)

Generates text using AI models.

Parameters

• service (string): AI service provider (openai, anthropic, vertexai, etc.)
• model (string): Model name
• messages (array): Array of message objects
• maxTokens (number, optional): Maximum tokens to generate
• temperature (number, optional): Temperature (0-1)
• topP (number, optional): Top P sampling
• frequencyPenalty (number, optional): Frequency penalty
• presencePenalty (number, optional): Presence penalty
• stopSequences (array, optional): Stop sequences
• tools (array, optional): Tools to use
• toolChoice (string, optional): Tool choice
• enabledTools (array, optional): Enabled tools
• userId (string, optional): User ID (for agent mode)

Usage Example

// Regular mode
const response = await client.generate({
    service: 'openai',
    model: 'gpt-4o',
    messages: [{ role: 'user', content: 'Hello' }]
});

// Agent mode
const agentResponse = await agentClient.generate({
    service: 'openai',
    model: 'gpt-4o',
    messages: [{ role: 'user', content: 'Hello' }]
});

2. stream({ service, model, messages, ...options })

Streams text generation using the specified AI service and model.

Parameters

Same as generate(), plus:

• streamOptions (object, optional): Stream-specific configuration options

Response Format

The stream emits Server-Sent Events (SSE) with two types of messages:

• Content Chunks:

{
    "content": "Generated text chunk",
    "role": "assistant"
}

• Final Statistics:

{
    "type": "done",
    "tokenUsage": 17,
    "cost": 0.000612
}

Usage Example

// Regular mode
const streamResponse = await client.stream({
    service: 'openai',
    model: 'gpt-4o',
    messages: [{ role: 'user', content: 'Hello' }]
});

// Agent mode
const agentStreamResponse = await agentClient.stream({
    service: 'openai',
    model: 'gpt-4o',
    messages: [{ role: 'user', content: 'Hello' }]
});

// Process the stream
const reader = streamResponse.body.getReader();
const decoder = new TextDecoder();

while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    
    const chunk = decoder.decode(value);
    const lines = chunk.split('\n');
    
    for (const line of lines) {
        if (line.startsWith('data: ')) {
            const data = JSON.parse(line.slice(6));
            if (data.type === 'done') {
                console.log('Stream stats:', {
                    tokenUsage: data.tokenUsage,
                    cost: data.cost
                });
            } else {
                console.log('Content:', data.content);
            }
        }
    }
}

3. listModels()

Lists all available models.

const models = await client.listModels();

4. testAPIConnection()

Tests the connection to the API.

const isConnected = await client.testAPIConnection();

5. genImage(options)

Generates images using AI models.

Parameters

• prompt (string): Image description
• width (number, optional): Image width
• height (number, optional): Image height
• maxTokens (number, optional): Maximum tokens
• temperature (number, optional): Temperature (0-1)
• steps (number, optional): Generation steps
• guidance (number, optional): Guidance scale
• seed (number, optional): Random seed
• image_count (number, optional): Number of images to generate
• image_quality (string, optional): Image quality
• image_format (string, optional): Image format
• model (string, optional): Model name ('stability.stable-image-ultra-v1:1' or 'imagen')

Usage Example

// Stability AI example
const stabilityResponse = await client.genImage({
    prompt: 'A beautiful sunset over mountains',
    width: 512,
    height: 512,
    model: 'stability.stable-image-ultra-v1:1',
    steps: 30,
    guidance: 7.5
});

// Imagen example
const imagenResponse = await client.genImage({
    prompt: 'A futuristic cityscape at night',
    width: 1024,
    height: 1024,
    model: 'imagen',
    steps: 50,
    guidance: 8.5,
    image_quality: 'high',
    image_format: 'png'
});

6. isNSFW(image)

Checks if an image is NSFW (Not Safe For Work).

Parameters

• image (object): Image data object
  • data (string): Base64 encoded image data
  • mimeType (string): MIME type of the image (e.g., 'image/png', 'image/jpeg')

Usage Example

const nsfwResult = await client.isNSFW({
    data: base64ImageData,
    mimeType: 'image/png'
});

7. textToSpeech(text)

Converts text to speech.

Parameters

• text (string): Text to convert to speech

Usage Example

const audioBlob = await client.textToSpeech('Hello, world!');

8. speechToText(audioBase64)

Converts speech to text.

Parameters

• audioBase64 (string): Base64 encoded audio file

Usage Example

const transcription = await client.speechToText(base64AudioData);

9. processImages(options)

Processes images using Vision AI.

Parameters

• prompt (string): Description of what to analyze
• images (string[]): Array of base64 encoded images

Usage Example

const analysis = await client.processImages({
    prompt: 'Describe what you see in this image',
    images: [base64ImageData]
});

Important Notes

Image Storage

Generated images are temporarily stored on the server and will be automatically deleted after a period of time. It is recommended to:

• Download and store generated images in your own storage system
• For Stability AI images, save the URLs immediately after generation
• For Imagen images, save the base64 data to your storage

Audio Storage

Generated audio files from Text-to-Speech are also temporarily stored. Make sure to:

• Save the audio blob to your storage system
• Handle the audio data immediately after generation

Error Handling

All methods throw errors if the API request fails:

try {
    const response = await client.generate({
        service: 'openai',
        model: 'gpt-4o',
        messages: [{ role: 'user', content: 'Hello' }]
    });
} catch (error) {
    console.error('Error:', error.message);
}

Authentication

The client supports two authentication modes:

• Regular Mode (default)

  • Uses API key in request headers
  • Initialize with: new EmbedAPIClient('your-api-key')

• Agent Mode

  • Uses agent ID in request body
  • Initialize with: new EmbedAPIClient('your-agent-id', { isAgent: true })
  • Optional userId parameter available for request tracking

License

MIT