API Reference

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

Namaste Tools provides a REST API that lets developers and LLMs access our six AI tools programmatically. Every tool follows the same async workflow: submit a request, poll status, then fetch results.

Quick Start

Base URL

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

Authentication

All API requests require your API key in the Authorization header:

Authorization: Key YOUR_API_KEY

Content Type

All requests use JSON:

Content-Type: application/json

Async Processing Workflow

Step 1: Submit

POST /api/models/{model_name} returns a request_id and the follow-up endpoints.

Submit Response (202 Accepted):

{
  "request_id": "req_1706352000_abc123def",
  "status": "queued",
  "message": "ai-image-watermark-remover request queued for processing",
  "estimated_completion_time": "45 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"
  }
}

Step 2: Poll Status

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

Status Response (200 OK):

{
  "request_id": "req_1706352000_abc123def",
  "tool_name": "ai-image-watermark-remover",
  "status": "in_progress",
  "progress": {
    "percentage": 10,
    "stage": "Processing",
    "description": "Job is currently being processed"
  },
  "created_at": "2025-01-27T10:30:00.000Z",
  "updated_at": "2025-01-27T10:30:00.000Z",
  "endpoints": {
    "result": "/api/models/ai-image-watermark-remover/requests/req_1706352000_abc123def"
  }
}

progress is an object with percentage, stage, and description. updated_at reflects the completion timestamp when available; otherwise it mirrors created_at.

Step 3: Get Result

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

Result (202 Accepted - still processing or finalizing billing):

{
  "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"
  }
}

Result (400 - failed):

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

Result (200 OK - 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": {
    "image": {
      "url": "https://cdn.namaste.tools/processed/abc123.png",
      "content_type": "image/png",
      "file_name": "result.png",
      "file_size": 2048576,
      "width": 1920,
      "height": 1080
    }
  },
  "metadata": {
    "originalFileName": "api-request-1706352000"
  }
}

Models (All 6 AI Tools)

Each tool has a dedicated endpoint and its own request payload. Use GET /api/models/{model_name} to retrieve authoritative input_schema and output_schema for LLMs and client generators.

1) AI Image Watermark Remover

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

Request:

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

Result payload (completed): result.image object (see output schema).

2) AI Image Editor

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

Request:

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

Result payload (completed): result.images[] with edited image URLs plus result.description.

3) AI Background Remover

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

Request:

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

Result payload (completed): result.image object (see output schema).

4) AI Image Upscaler

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

Request:

{
  "image_url": "https://example.com/image.jpg",
  "scale": 2
}

Result payload (completed): result.image object (see output schema).

5) AI PDF Watermark Remover

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

Request:

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

Result payload (completed): see tool output schema via GET /api/models/ai-pdf-watermark-remover.

6) AI Video Watermark Remover

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

Request:

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

Result payload (completed): see tool output schema via GET /api/models/ai-video-watermark-remover.

Discovery Endpoints (Useful for LLMs)

List Models

GET /api/models

Get Model Schema

GET /api/models/{model_name}

This returns input_schema and output_schema so LLMs can self-configure payloads.

Request Payload Rules

Required (one of):

image_url (string URL)
image_urls (array of URLs, first URL is used)
pdf_url (string URL)
video_url (string URL)

Optional (tool-specific):

prompt (string) — used by ai-image-editor (optional)
output_format (png | jpeg | webp) — only forwarded for ai-image-editor
scale (number 1–4) — only for ai-image-upscaler
quality (number 1–100) — accepted but currently ignored

Rate Limits

Per account + API key: 30 requests / minute (queued)
This is enforced in-memory today and will expand to Redis for multi-instance deployments. A Retry-After header and retry_after_ms are returned on 429.

Error Handling

HTTP Status Codes

200: Success (GET)
202: Accepted (POST enqueued)
400: Bad Request (invalid input or malformed JSON)
401: Unauthorized (invalid API key)
402: Payment Required (insufficient credits)
403: Forbidden (request belongs to a different account)
404: Not Found (invalid tool/model name or request id)
429: Too Many Requests (rate limit exceeded)
500: Internal Server Error

Common Error Codes

AUTHENTICATION_FAILED: Missing/invalid API key or authorization header
INVALID_TOOL: The specified tool/model name is not valid or supported
INVALID_CONTENT_TYPE: Content-Type must be application/json
INVALID_JSON: The request body contains malformed JSON
VALIDATION_ERROR: Input failed validation (see details)
MISSING_FILE_URL: No image_url, image_urls, pdf_url, or video_url was provided
INSUFFICIENT_CREDITS: Not enough credits to process the request (can occur at submit time or when charging after completion)
CREDIT_CONSUMPTION_ERROR: Failed while checking or charging credits
QUEUE_ERROR: Failed to enqueue 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
REQUEST_NOT_FOUND: The request id does not exist
FORBIDDEN: The request exists but belongs to another account
PROCESSING_FAILED: The processing request failed due to invalid input or server error
PROCESSING_ERROR: Unexpected server error while processing the request

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"
}

Insufficient Credits (402):

{
  "error": "No credits available",
  "code": "INSUFFICIENT_CREDITS",
  "current_credits": 0,
  "required_credits": 2
}

Request Not Found (404):

{
  "error": "Request not found",
  "code": "REQUEST_NOT_FOUND",
  "message": "No request found with ID: req_123"
}

Rate Limited (429):

{
  "error": "Too Many Requests",
  "code": "RATE_LIMITED",
  "retry_after_ms": 60000
}

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
Credits are validated at submission time, and charged only after successful processing
Failed requests don't consume credits
If credits are exhausted before completion, the result endpoint returns 402 until credits are available

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

Sign up for an account at namaste.tools
Purchase credits through our billing system
Use your API key to make requests
Credits are automatically deducted after 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

Webhooks are not available in the current Models API. Use polling with the status and result endpoints.

Best Practices

Performance

Use appropriate image sizes for your use case
Implement proper error handling and retry logic
Cache results when possible
Use polling 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!