Complete API Reference

Full documentation of all UlazAI API endpoints, authentication methods, and error handling.

📋 Table of Contents

🔐 Authentication

UlazAI supports two authentication methods: Token Authentication and API Key Authentication.

POST /api/register/

Create a new user account

Request Body

{
  "username": "johndoe",
  "email": "[email protected]",
  "password": "secure_password123"
}

Response (201 Created)

{
  "token": "your-auth-token-here",
  "user": {
    "id": 1,
    "username": "johndoe",
    "email": "[email protected]",
    "credits_balance": 0
  }
}
POST /api/login/

Login with username and password to get authentication token

Request Body

{
  "username": "johndoe",
  "password": "secure_password123"
}

Response (200 OK)

{
  "token": "your-auth-token-here",
  "user": {
    "id": 1,
    "username": "johndoe",
    "email": "[email protected]",
    "credits_balance": 100
  }
}
POST /api/api-keys/ Auth Required

Create a new API key for authentication

Request Headers

Authorization: Token your-auth-token-here

Request Body

{
  "name": "Production API Key"
}

Response (201 Created)

{
  "id": "uuid-here",
  "name": "Production API Key",
  "key": "ulazai_live_abc123...", // Only shown once!
  "key_preview": "ulazai_li...",
  "created_at": "2025-01-15T10:00:00Z"
}

⚠️ Important: The full API key is only shown once during creation. Store it securely!

Using Authentication

Token Authentication

Authorization: Token your-auth-token-here

API Key Authentication

Authorization: Bearer ulazai_live_abc123...

🎨 Image Generation

POST /api/v1/generate/ Auth Required

Generate a new image from a text prompt

Request Body

{
  "prompt": "A beautiful sunset over mountains with a lake in foreground",
  "size": "3:2"  // Options: "1:1", "3:2", "2:3"
}

Response (201 Created)

{
  "success": true,
  "data": {
    "generation_id": "uuid-here",
    "status": "processing",
    "credits_used": 8,
    "credits_remaining": 92,
    "message": "Image generation started successfully"
  }
}

Credit Cost

All image sizes cost 8 credits per generation

GET /api/v1/generate/history/ Auth Required

Get your generation history

Query Parameters

?limit=20&offset=0&type=image

🎬 Video Generation

POST /api/v1/generate/video/ Auth Required

Generate a new video from text or image

Request Body

{
  "prompt": "A cat playing in a garden",
  "video_model": "veo3_fast",  // Options: "veo3_fast", "veo3"
  "aspect_ratio": "16:9",      // Options: "16:9", "9:16"
  "watermark_text": "MyBrand", // Optional, max 50 chars
  "source_image_urls": []      // Optional, for image-to-video
}

Credit Costs

• veo3_fast (16:9): 130 credits

• veo3_fast (9:16): 150 credits

• veo3 (all ratios): 300 credits

📊 Status Checking

GET /api/v1/generate/{generation_id}/ Auth Required

Check the status of any generation (image or video)

Response (200 OK)

{
  "id": "uuid-here",
  "generation_type": "video",
  "status": "completed",
  "prompt": "A cat playing in a garden",
  "video_url": "https://cdn.ulazai.com/videos/...",
  "video_model": "veo3_fast",
  "credits_used": 130,
  "created_at": "2025-01-15T10:00:00Z",
  "completed_at": "2025-01-15T10:01:30Z"
}

👤 User Management

GET /api/profile/ Auth Required

Get current user profile information

Response (200 OK)

{
  "id": 1,
  "username": "johndoe",
  "email": "[email protected]",
  "credits_balance": 92,
  "total_images_generated": 12,
  "enable_watermark": true,
  "watermark_text": "MyBrand",
  "created_at": "2025-01-10T08:00:00Z"
}
PUT /api/profile/ Auth Required

Update user profile settings

Request Body

{
  "enable_watermark": true,
  "watermark_text": "MyBrand.com"
}

💳 Payments & Credits

GET /payments/api/credits/ Auth Required

Get current credit balance

Response (200 OK)

{
  "credits_balance": 92,
  "total_spent": "25.00",
  "total_credits_purchased": 2400
}
GET /payments/api/transactions/ Auth Required

Get transaction history

❌ Error Handling

Standard Error Response Format

{
  "success": false,
  "error": "Error message here",
  "details": {
    "field_name": "Specific field error"
  }
}
400 Bad Request Invalid request parameters

The request is malformed or missing required fields

401 Unauthorized Missing or invalid authentication

No valid authentication token or API key provided

402 Payment Required Insufficient credits

Not enough credits to complete the requested operation

403 Forbidden Access denied

You don't have permission to access this resource

404 Not Found Resource not found

The requested resource doesn't exist

429 Too Many Requests Rate limit exceeded

Too many requests in a short period. Please slow down

500 Internal Server Error Server error

Something went wrong on our end. Please try again

🚦 Rate Limits

Authenticated Users 100 requests/minute
Demo Users 10 requests/hour
Concurrent Generations 5 per user

📝 Complete Example

Python Example

import requests
import time

# Configuration
API_KEY = "ulazai_live_your_api_key_here"
BASE_URL = "https://ulazai.com"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Generate a video
video_data = {
    "prompt": "A beautiful sunset timelapse over the ocean",
    "video_model": "veo3_fast",
    "aspect_ratio": "16:9",
    "watermark_text": "MyBrand"
}

response = requests.post(f"{BASE_URL}/api/v1/generate/video/", 
                        json=video_data, headers=headers)

if response.status_code == 201:
    result = response.json()
    generation_id = result["data"]["generation_id"]
    print(f"Video generation started: {generation_id}")
    
    # Poll for status
    while True:
        status_response = requests.get(
            f"{BASE_URL}/api/v1/generate/{generation_id}/", 
            headers=headers
        )
        status_data = status_response.json()
        
        if status_data["status"] == "completed":
            print(f"Video ready: {status_data['video_url']}")
            break
        elif status_data["status"] == "failed":
            print(f"Generation failed: {status_data.get('error_message')}")
            break
        
        print(f"Status: {status_data['status']}...")
        time.sleep(10)  # Wait 10 seconds before next check
else:
    print(f"Error: {response.json()}")

🤝 Need Help?

• WhatsApp: Ask us anything

• Documentation: docs.ulazai.com