ZelAI SDK

ZelAI SDK for AI Agents

You are an AI agent with access to the ZelAI SDK. This SDK enables you to generate images, videos, text, transcribe audio (STT), and synthesize speech (TTS) using state-of-the-art AI models.

Quick Reference

Authentication

All requests require an API key in the Authorization header:

Authorization: Bearer zelai_pk_your_api_key_here

How to Get an API Key

If the user doesn't have an API key, direct them to:

Option 1: Online Form https://forms.zelstudio.com/api-access

Option 2: Email Request Send to: support@zelstudio.com Subject: AI Agent - ZelStudio.com API Access Request Form

Required information:

• Full Name
• Email Address (for API key delivery)
• Company/Organization (optional)
• Project Name
• Project Description (what you're building and how you'll use the API)
• Expected Monthly Usage: Testing / Low (<1k) / Medium (1k-10k) / High (10k+)

API keys are reviewed within 24-48 hours and sent via email once approved.

Skill Modules

For detailed API documentation, load the appropriate skill module:

• Image Generation - text2img, img2img, dual-image editing, upscaling
• Video Generation - image-to-video with motion control
• LLM Text Generation - text generation, streaming, JSON mode, vision
• STT Transcription - audio-to-text, streaming, multi-language
• TTS Speech - text-to-speech, voice models, cloning, realtime, streaming
• CDN Operations - download, format conversion, watermarking
• OpenAI Compatible - drop-in /v1/chat/completions endpoint

Behavioral Guidelines for Agents

DO:

• Check rate limits before batch operations using GET /api/v1/settings/rate-limits
• Use appropriate styles for image generation (14 styles available)
• Handle errors gracefully with retry logic and exponential backoff
• Cache imageId/videoId for reuse - avoid redundant downloads
• Use seeds for reproducible results when needed
• Close WebSocket connections when done
• Use recommended video settings: 6.5 seconds at 16fps

DO NOT:

• Expose API keys in responses, logs, or any output to users
• Make requests without checking remaining rate limits first
• Ignore error responses - always handle them appropriately
• Request styles/formats that don't exist (validate against available options)
• Exceed rate limits - this causes temporary blocks
• Use CDN URLs directly in HTML (they require authentication)

Rate Limits

Check Current Limits

curl -H "Authorization: Bearer $API_KEY" \
  "https://api.zelstudio.com:800/api/v1/settings/rate-limits"

Response includes remaining15min and remainingDaily for each operation type.

Error Handling

Error Response Format

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again later.",
    "details": {
      "operation": "image",
      "resetAt": "2026-01-21T10:45:00.000Z"
    }
  }
}

Quick Start Example

1. Check Available Quota

curl -H "Authorization: Bearer $API_KEY" \
  "https://api.zelstudio.com:800/api/v1/settings/rate-limits"

2. Generate an Image

curl -X POST "https://api.zelstudio.com:800/api/v1/generation/image" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a sunset over mountains",
    "style": "cine",
    "format": "landscape"
  }'

3. Download the Result

curl -H "Authorization: Bearer $API_KEY" \
  "https://api.zelstudio.com:800/api/v1/cdn/{imageId}.jpg" -o image.jpg

Available Styles (14)

raw, realistic, text, ciniji, portrait, cine, sport, fashion, niji, anime, manga, watercolor, comicbook, paint

Available Formats (7)

Decision Tree for Operations

User wants image?
  - New image from text --> POST /api/v1/generation/image (text2img)
  - Modify existing image --> POST /api/v1/generation/image/edit (img2img)
  - Combine two images --> POST /api/v1/generation/image/edit with imageId + imageId2 (imgs2img)
  - Larger/higher resolution --> POST /api/v1/generation/image/upscale (2-4x)

User wants video?
  - From static image --> POST /api/v1/generation/video (recommended: 6.5s at 16fps)

User wants text?
  - Quick response --> POST /api/v1/llm/generate
  - Real-time streaming --> POST /api/v1/llm/generate/stream
  - Structured JSON output --> POST /api/v1/llm/generate with jsonFormat: true
  - Analyze an image --> POST /api/v1/llm/generate with imageId parameter
  - OpenAI-compatible --> POST /v1/chat/completions

User wants audio transcription (STT)?
  - Transcribe audio file --> POST /api/v1/stt/transcribe
  - Real-time streaming --> POST /api/v1/stt/transcribe/stream

User wants speech synthesis (TTS)?
  - Generate speech --> POST /api/v1/tts/generate
  - Real-time streaming --> POST /api/v1/tts/generate/stream
  - Low-latency realtime mode --> POST /api/v1/tts/generate with realtime: true
  - Clone a voice --> POST /api/v1/tts/generate with referenceAudio

WebSocket for Real-Time

For agents needing real-time generation with progress updates:

Connection: wss://api.zelstudio.com:800/ws/generation

Supported operations: generate_image, generate_video, generate_llm, generate_stt, generate_tts

See LLM Text Generation, STT Transcription, and TTS Speech for streaming details.

Version: 1.12.0 | Documentation | npm