Namaste Tools Logo - Light Theme

API Reference

Complete API documentation for all Namaste Tools AI models and endpoints.

Namaste Tools provides a comprehensive REST API that allows developers to integrate our AI-powered tools directly into their applications. Our API offers programmatic access to all our AI models with detailed documentation, examples, and SDKs.

Quick Start

Base URL

https://www.namaste.tools/api/

Authentication

All API requests require authentication using your API key:

Authorization: Key YOUR_API_KEY

Content Type

All requests should use JSON format:

Content-Type: application/json

Available AI Models

Our API provides access to 6 professional AI models:

1. Image Watermark Remover

Remove watermarks from images using advanced AI technology.

Endpoint: POST /api/models/ai-ai-image-watermark-remover

Input:

{
  "image_url": "https://example.com/image.jpg",
  "output_format": "png"
}

Response (202 Accepted):

{
  "request_id": "req_1706352000_abc123def",
  "status": "processing",
  "message": "ai-image-watermark-remover request submitted successfully",
  "estimated_completion_time": "30-60 seconds",
  "endpoints": {
    "status": "/api/models/ai-image-watermark-remover/requests/req_1706352000_abc123def/status",
    "result": "/api/models/ai-image-watermark-remover/requests/req_1706352000_abc123def"
  }
}

2. Image Editor

Edit and transform images using AI with text prompts.

Endpoint: POST /api/models/ai-image-editor

Input:

{
  "image_urls": ["https://example.com/image.jpg"],
  "prompt": "Remove the background and add a sunset sky",
  "output_format": "png"
}

3. Background Remover

Automatically remove backgrounds from images with precision.

Endpoint: POST /api/models/ai-background-remover

Input:

{
  "image_url": "https://example.com/image.jpg",
  "output_format": "png"
}

4. Image Upscaler

Enhance image resolution using AI technology.

Endpoint: POST /api/models/ai-image-upscaler

Input:

{
  "image_url": "https://example.com/image.jpg",
  "scale_factor": 4,
  "model": "general"
}

5. PDF Watermark Remover

Remove watermarks from PDF documents using advanced AI.

Endpoint: POST /api/models/ai-pdf-watermark-remover

Input:

{
  "pdf_url": "https://example.com/document.pdf",
  "output_format": "pdf"
}

6. Video Watermark Remover

Remove watermarks from video files using cutting-edge AI.

Endpoint: POST /api/models/ai-video-watermark-remover

Input:

{
  "video_url": "https://example.com/video.mp4",
  "output_format": "mp4"
}

Processing Workflow

Namaste Tools API uses an asynchronous queue-based processing system. Here's how it works:

1. Submit Request

Send a POST request to the model endpoint with your input data. The API immediately returns a request_id and status processing.

2. Poll for Status

Use the status endpoint to check the progress of your request. The status can be:

  • processing: Request is being processed
  • completed: Processing finished successfully
  • failed: Processing failed due to an error

3. Get Results

Once the status is completed, use the result endpoint to retrieve the final processed data.

Processing Flow Example

graph TD
    A[Submit Request] --> B[Get Request ID]
    B --> C[Poll Status Endpoint]
    C --> D{Status?}
    D -->|processing| E[Wait 5 seconds]
    E --> C
    D -->|completed| F[Get Result]
    D -->|failed| G[Handle Error]
    F --> H[Download Result]

API Endpoints

List All Models

Get information about all available AI models.

GET /api/models

Response:

{
  "tools": [
    {
      "name": "ai-image-watermark-remover",
      "credits_per_use": 2,
      "categories": ["image", "ai"],
      "demo_url": "https://www.namaste.tools/tools/ai-image-watermark-remover",
      "documentation_url": "https://www.namaste.tools/docs/api/ai-image-watermark-remover",
      "input_schema": {
        "type": "object",
        "properties": {
          "image_url": {"type": "string", "format": "uri"},
          "output_format": {"type": "string", "enum": ["png", "jpg", "webp"]}
        },
        "required": ["image_url"]
      },
      "output_schema": {
        "type": "object",
        "properties": {
          "images": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "url": {"type": "string"},
                "content_type": {"type": "string"},
                "file_name": {"type": "string"},
                "file_size": {"type": "number"},
                "width": {"type": "number"},
                "height": {"type": "number"}
              }
            }
          },
          "processing_time": {"type": "number"}
        }
      },
      "endpoints": {
        "process": "/api/models/ai-image-watermark-remover",
        "status": "/api/models/ai-image-watermark-remover/requests/:requestId/status",
        "result": "/api/models/ai-image-watermark-remover/requests/:requestId"
      }
    }
  ],
  "total_count": 6,
  "api_version": "1.0.0",
  "documentation": "https://www.namaste.tools/api"
}

Get Model Information

Get detailed information about a specific model.

GET /api/models/{model_name}

Response:

{
  "name": "ai-image-watermark-remover",
  "credits_per_use": 2,
  "categories": ["image", "ai"],
  "demo_url": "https://www.namaste.tools/tools/ai-image-watermark-remover",
  "documentation_url": "https://www.namaste.tools/docs/api/ai-image-watermark-remover",
  "input_schema": { ... },
  "output_schema": { ... },
  "endpoints": {
    "process": "/api/models/ai-image-watermark-remover",
    "status": "/api/models/ai-image-watermark-remover/requests/:requestId/status",
    "result": "/api/models/ai-image-watermark-remover/requests/:requestId"
  }
}

Submit Processing Request

Submit a file for AI processing. This returns immediately with a request ID for tracking.

POST /api/models/{model_name}

Example Request:

{
  "image_url": "https://example.com/image.jpg",
  "output_format": "png"
}

Example Response (202 Accepted):

{
  "request_id": "req_1706352000_abc123def",
  "status": "processing",
  "message": "ai-image-watermark-remover request submitted successfully",
  "estimated_completion_time": "30-60 seconds",
  "endpoints": {
    "status": "/api/models/ai-image-watermark-remover/requests/req_1706352000_abc123def/status",
    "result": "/api/models/ai-image-watermark-remover/requests/req_1706352000_abc123def"
  }
}

Check Request Status

Check the status of a processing request.

GET /api/models/{model_name}/requests/{request_id}/status

Response:

{
  "request_id": "req_1706352000_abc123def",
  "tool_name": "ai-image-watermark-remover",
  "status": "completed",
  "progress": 100,
  "message": "ai-image-watermark-remover processing completed successfully",
  "result_url": "https://cdn.namaste.tools/processed/ai-image-watermark-remover/req_1706352000_abc123def_result.png",
  "created_at": "2025-01-27T10:30:00.000Z",
  "updated_at": "2025-01-27T10:30:45.000Z",
  "endpoints": {
    "result": "/api/models/ai-image-watermark-remover/requests/req_1706352000_abc123def"
  }
}

Get Processing Result

Get the final result of a completed processing request.

GET /api/models/{model_name}/requests/{request_id}

Response (Completed):

{
  "request_id": "req_1706352000_abc123def",
  "tool_name": "ai-image-watermark-remover",
  "status": "completed",
  "message": "ai-image-watermark-remover processing completed successfully",
  "created_at": "2025-01-27T10:30:00.000Z",
  "completed_at": "2025-01-27T10:30:45.000Z",
  "result_url": "https://cdn.namaste.tools/processed/ai-image-watermark-remover/req_1706352000_abc123def_result.png",
  "original_url": "https://cdn.namaste.tools/input/ai-image-watermark-remover/req_1706352000_abc123def_original.png",
  "metadata": {
    "width": 1920,
    "height": 1080,
    "format": "PNG",
    "size_bytes": 2048576,
    "processing_time_ms": 45000
  }
}

Response (Still Processing - 202 Accepted):

{
  "request_id": "req_1706352000_abc123def",
  "tool_name": "ai-image-watermark-remover",
  "status": "processing",
  "message": "ai-image-watermark-remover is still being processed. Please check the status endpoint.",
  "created_at": "2025-01-27T10:30:00.000Z",
  "endpoints": {
    "status": "/api/models/ai-image-watermark-remover/requests/req_1706352000_abc123def/status"
  }
}

Code Examples

cURL

# Submit processing request
curl -X POST "https://www.namaste.tools/api/models/ai-image-watermark-remover" \
  -H "Authorization: Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/image.jpg",
    "output_format": "png"
  }'

# Check status
curl -X GET "https://www.namaste.tools/api/models/ai-image-watermark-remover/requests/req_1706352000_abc123def/status" \
  -H "Authorization: Key YOUR_API_KEY"

# Get result
curl -X GET "https://www.namaste.tools/api/models/ai-image-watermark-remover/requests/req_1706352000_abc123def" \
  -H "Authorization: Key YOUR_API_KEY"

JavaScript/Node.js

// Submit processing request
const submitResponse = await fetch(
  'https://www.namaste.tools/api/models/ai-image-watermark-remover',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Key YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      image_url: 'https://example.com/image.jpg',
      output_format: 'png'
    })
  }
);

if (submitResponse.status === 202) {
  const { request_id } = await submitResponse.json();
  console.log('Request submitted:', request_id);
  
  // Poll for completion
  let completed = false;
  while (!completed) {
    const statusResponse = await fetch(
      `https://www.namaste.tools/api/models/ai-image-watermark-remover/requests/${request_id}/status`,
      {
        headers: {
          'Authorization': 'Key YOUR_API_KEY'
        }
      }
    );
    
    const status = await statusResponse.json();
    console.log('Status:', status.status, 'Progress:', status.progress + '%');
    
    if (status.status === 'completed') {
      // Get final result
      const resultResponse = await fetch(
        `https://www.namaste.tools/api/models/ai-image-watermark-remover/requests/${request_id}`,
        {
          headers: {
            'Authorization': 'Key YOUR_API_KEY'
          }
        }
      );
      
      const result = await resultResponse.json();
      console.log('Result URL:', result.result_url);
      completed = true;
    } else if (status.status === 'failed') {
      console.error('Processing failed:', status.error);
      break;
    } else {
      // Wait 5 seconds before checking again
      await new Promise(resolve => setTimeout(resolve, 5000));
    }
  }
} else {
  console.error('Error:', submitResponse.statusText);
}

Python

import requests
import time

# Submit processing request
url = "https://www.namaste.tools/api/models/ai-image-watermark-remover"
headers = {
    "Authorization": "Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

data = {
    "image_url": "https://example.com/image.jpg",
    "output_format": "png"
}

response = requests.post(url, headers=headers, json=data)

if response.status_code == 202:
    result = response.json()
    request_id = result["request_id"]
    print(f"Request submitted: {request_id}")
    
    # Poll for completion
    while True:
        status_response = requests.get(
            f"https://www.namaste.tools/api/models/ai-image-watermark-remover/requests/{request_id}/status",
            headers=headers
        )
        
        status = status_response.json()
        print(f"Status: {status['status']}, Progress: {status['progress']}%")
        
        if status["status"] == "completed":
            # Get final result
            result_response = requests.get(
                f"https://www.namaste.tools/api/models/ai-image-watermark-remover/requests/{request_id}",
                headers=headers
            )
            
            result = result_response.json()
            print(f"Result URL: {result['result_url']}")
            break
        elif status["status"] == "failed":
            print(f"Processing failed: {status['error']}")
            break
        else:
            # Wait 5 seconds before checking again
            time.sleep(5)
else:
    print(f"Error: {response.status_code}")

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "time"
)

type RequestData struct {
    ImageURL     string `json:"image_url"`
    OutputFormat string `json:"output_format"`
}

type SubmitResponse struct {
    RequestID string `json:"request_id"`
    Status    string `json:"status"`
    Message   string `json:"message"`
}

type StatusResponse struct {
    RequestID string `json:"request_id"`
    Status    string `json:"status"`
    Progress  int    `json:"progress"`
    Message   string `json:"message"`
}

type ResultResponse struct {
    RequestID  string `json:"request_id"`
    Status     string `json:"status"`
    ResultURL  string `json:"result_url"`
    Message    string `json:"message"`
}

func main() {
    baseURL := "https://www.namaste.tools/api/models/ai-image-watermark-remover"
    apiKey := "YOUR_API_KEY"
    
    // Submit request
    data := RequestData{
        ImageURL:     "https://example.com/image.jpg",
        OutputFormat: "png",
    }
    
    jsonData, err := json.Marshal(data)
    if err != nil {
        panic(err)
    }
    
    req, err := http.NewRequest("POST", baseURL, bytes.NewBuffer(jsonData))
    if err != nil {
        panic(err)
    }
    
    req.Header.Set("Authorization", "Key "+apiKey)
    req.Header.Set("Content-Type", "application/json")
    
    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()
    
    if resp.StatusCode == 202 {
        var submitResp SubmitResponse
        json.NewDecoder(resp.Body).Decode(&submitResp)
        fmt.Printf("Request submitted: %s\n", submitResp.RequestID)
        
        // Poll for completion
        for {
            statusReq, err := http.NewRequest("GET", 
                fmt.Sprintf("%s/requests/%s/status", baseURL, submitResp.RequestID), nil)
            if err != nil {
                panic(err)
            }
            statusReq.Header.Set("Authorization", "Key "+apiKey)
            
            statusResp, err := client.Do(statusReq)
            if err != nil {
                panic(err)
            }
            
            var status StatusResponse
            json.NewDecoder(statusResp.Body).Decode(&status)
            statusResp.Body.Close()
            
            fmt.Printf("Status: %s, Progress: %d%%\n", status.Status, status.Progress)
            
            if status.Status == "completed" {
                // Get final result
                resultReq, err := http.NewRequest("GET", 
                    fmt.Sprintf("%s/requests/%s", baseURL, submitResp.RequestID), nil)
                if err != nil {
                    panic(err)
                }
                resultReq.Header.Set("Authorization", "Key "+apiKey)
                
                resultResp, err := client.Do(resultReq)
                if err != nil {
                    panic(err)
                }
                defer resultResp.Body.Close()
                
                var result ResultResponse
                json.NewDecoder(resultResp.Body).Decode(&result)
                fmt.Printf("Result URL: %s\n", result.ResultURL)
                break
            } else if status.Status == "failed" {
                fmt.Println("Processing failed")
                break
            }
            
            time.Sleep(5 * time.Second)
        }
    } else {
        fmt.Printf("Error: %d\n", resp.StatusCode)
    }
}

File Requirements

Supported Formats

  • Images: JPG, JPEG, PNG, WebP, TIFF, BMP
  • PDFs: PDF
  • Videos: MP4, AVI, MOV, WebM

File Size Limits

  • Images: Maximum 10MB
  • PDFs: Maximum 50MB
  • Videos: Maximum 2GB, 10 minutes duration

Processing Timeouts

  • Images: 30 seconds
  • PDFs: 2 minutes
  • Videos: 30 minutes

Rate Limits

  • Free Tier: 100 requests per minute
  • Paid Plans: Higher limits based on subscription
  • Burst Allowance: Temporary spikes in usage are accommodated

Error Handling

HTTP Status Codes

  • 200: Success (for GET requests)
  • 202: Accepted (for POST requests - processing started)
  • 400: Bad Request (invalid input or malformed JSON)
  • 401: Unauthorized (invalid API key)
  • 404: Not Found (invalid tool/model name)
  • 429: Too Many Requests (rate limit exceeded)
  • 500: Internal Server Error

Error Response Format

{
  "error": "Invalid or unsupported tool",
  "code": "INVALID_TOOL"
}

Common Error Codes

  • INVALID_TOOL: The specified tool/model name is not valid or supported
  • INVALID_JSON: The request body contains malformed JSON
  • PROCESSING_ERROR: An error occurred while processing the request
  • MODELS_LIST_ERROR: Failed to retrieve the list of available models
  • TOOL_INFO_ERROR: Failed to retrieve tool information
  • STATUS_ERROR: Failed to retrieve request status
  • RESULT_ERROR: Failed to retrieve request result
  • PROCESSING_FAILED: The processing request failed due to invalid input or server error

Error Examples

Invalid Tool (404):

{
  "error": "Invalid or unsupported tool",
  "code": "INVALID_TOOL"
}

Malformed JSON (400):

{
  "error": "Invalid JSON in request body",
  "code": "INVALID_JSON"
}

Processing Failed (400):

{
  "request_id": "req_1706352000_abc123def",
  "tool_name": "ai-image-watermark-remover",
  "status": "failed",
  "error": "PROCESSING_FAILED",
  "message": "ai-image-watermark-remover processing failed due to invalid input or server error",
  "created_at": "2025-01-27T10:30:00.000Z",
  "failed_at": "2025-01-27T10:30:45.000Z"
}

Credit System

How Credits Work

  • Credits are consumed based on the complexity and size of the processing task
  • Each API endpoint has different credit costs
  • You only pay for successful processing - failed requests don't consume credits
  • Credits are purchased in advance and deducted per successful request

Credit Costs

  • Image Processing: 1-5 credits depending on size and complexity
  • PDF Processing: 2-10 credits depending on document size
  • Video Processing: 5-50 credits depending on duration and resolution

Getting Credits

  1. Sign up for an account at namaste.tools
  2. Purchase credits through our billing system
  3. Use your API key to make requests
  4. Credits are automatically deducted for successful processing

SDKs and Libraries

Official SDKs

  • JavaScript/Node.js: npm install @namaste-tools/api
  • Python: pip install namaste-tools
  • Go: go get github.com/namaste-tools/api-go

Community Libraries

  • PHP: Available on Packagist
  • Ruby: Available on RubyGems
  • Java: Available on Maven Central

Webhooks

Configure webhooks to receive notifications when processing is complete:

{
  "webhook_url": "https://your-app.com/webhook",
  "events": ["processing.completed", "processing.failed"]
}

Webhook Payload

{
  "event": "processing.completed",
  "request_id": "req_123456789",
  "model": "ai-image-watermark-remover",
  "result": {
    "images": [...]
  },
  "timestamp": "2025-01-27T10:30:00Z"
}

Best Practices

Performance

  • Use appropriate image sizes for your use case
  • Implement proper error handling and retry logic
  • Cache results when possible
  • Use webhooks for async processing

Security

  • Keep your API key secure and never expose it in client-side code
  • Use HTTPS for all requests
  • Validate input data before sending requests
  • Monitor your usage and set up alerts

Cost Optimization

  • Test with smaller files first
  • Use appropriate output formats
  • Implement proper error handling to avoid unnecessary retries
  • Monitor your credit usage

Support and Resources

Documentation

  • API Reference: Complete endpoint documentation
  • Code Examples: Examples in multiple programming languages
  • SDK Documentation: Detailed SDK usage guides

Support

  • Email: [email protected]
  • Discord: Join our developer community
  • Status Page: Check API status and uptime

Resources

  • Blog: Latest updates and tutorials
  • GitHub: Open source examples and tools
  • Changelog: API updates and new features

Ready to get started? Get your API key and begin integrating our AI tools into your applications today!