Integration Guide

How to Integrate CAPTCHA Solver API: Complete Guide

Step-by-step instructions and best practices for integrating AI4CAP.COM into your applications, with examples in multiple programming languages.

By Integration Team

•

December 28, 2023

•

25 min read

Quick Start: 5 Steps to Integration

Get API Key

2 min

Install SDK

Choose and install language SDK

5 min

Configure Client

Initialize with your API key

3 min

Implement Logic

Add CAPTCHA solving to your flow

10 min

Test & Deploy

Verify and go to production

5 min

Total Integration Time: ~25 minutes

Most developers complete their first integration in under 30 minutes

Language-Specific Integration

Python Integration

# 1. Install SDK
pip install ai4cap

# 2. Basic usage
from ai4cap import Client

# Initialize client
client = Client('your_api_key_here')

# Solve image CAPTCHA
with open('captcha.png', 'rb') as f:
    image_data = f.read()
    
result = client.solve({
    'type': 'image',
    'image': base64.b64encode(image_data).decode()
})

print(f"Solution: {result['solution']}")

# Solve reCAPTCHA v2
result = client.solve({
    'type': 'recaptcha_v2',
    'sitekey': '6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-',
    'pageurl': 'https://example.com'
})

print(f"Token: {result['solution']}")

Key Features:

• Async support with asyncio
• Type hints for better IDE support
• Automatic retry on failure
• Context manager support

JavaScript/Node.js Integration

// 1. Install SDK
npm install @ai4cap/sdk

// 2. Basic usage
const { AI4CAP } = require('@ai4cap/sdk');

// Initialize client
const client = new AI4CAP('your_api_key_here');

// Solve image CAPTCHA
const fs = require('fs');
const imageBase64 = fs.readFileSync('captcha.png', 'base64');

const result = await client.solve({
  type: 'image',
  image: imageBase64
});

console.log('Solution:', result.solution);

// Solve reCAPTCHA v2
const recaptchaResult = await client.solve({
  type: 'recaptcha_v2',
  sitekey: '6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-',
  pageurl: 'https://example.com'
});

console.log('Token:', recaptchaResult.solution);

Key Features:

• Promise-based API
• TypeScript definitions included
• Browser and Node.js support
• WebSocket support for real-time updates

Common Integration Patterns

const { AI4CAP } = require('@ai4cap/sdk');
const puppeteer = require('puppeteer');

class FormAutomation {
  constructor(apiKey) {
    this.captchaSolver = new AI4CAP(apiKey);
  }
  
  async submitFormWithCaptcha(formUrl, formData) {
    const browser = await puppeteer.launch({ headless: false });
    const page = await browser.newPage();
    
    try {
      // Navigate to form
      await page.goto(formUrl, { waitUntil: 'networkidle2' });
      
      // Fill form fields
      for (const [field, value] of Object.entries(formData)) {
        await page.type(`#${field}`, value);
      }
      
      // Handle CAPTCHA if present
      const captchaFrame = await page.$('iframe[src*="recaptcha"]');
      
      if (captchaFrame) {
        // Get sitekey
        const sitekey = await page.evaluate(() => {
          const elem = document.querySelector('.g-recaptcha');
          return elem ? elem.getAttribute('data-sitekey') : null;
        });
        
        if (sitekey) {
          // Solve reCAPTCHA
          const solution = await this.captchaSolver.solve({
            type: 'recaptcha_v2',
            sitekey: sitekey,
            pageurl: page.url()
          });
          
          // Inject solution
          await page.evaluate((token) => {
            document.getElementById('g-recaptcha-response').innerHTML = token;
            document.getElementById('g-recaptcha-response').style.display = '';
            
            // Trigger callback if exists
            if (window.___grecaptcha_cfg) {
              Object.entries(window.___grecaptcha_cfg.clients).forEach(([key, client]) => {
                if (client.callback) {
                  client.callback(token);
                }
              });
            }
          }, solution.solution);
        }
      }
      
      // Submit form
      await page.click('button[type="submit"]');
      await page.waitForNavigation();
      
      // Return success page content
      return await page.content();
      
    } finally {
      await browser.close();
    }
  }
}

using AI4CAP.SDK;
using Microsoft.AspNetCore.Mvc;

namespace YourApp.Controllers
{
    [ApiController]
    [Route("api/[controller]")]
    public class ProtectedResourceController : ControllerBase
    {
        private readonly IAI4CAPClient _captchaClient;
        private readonly IResourceService _resourceService;
        
        public ProtectedResourceController(
            IAI4CAPClient captchaClient,
            IResourceService resourceService)
        {
            _captchaClient = captchaClient;
            _resourceService = resourceService;
        }
        
        [HttpPost("access")]
        public async Task<IActionResult> AccessProtectedResource(
            [FromBody] ResourceRequest request)
        {
            try
            {
                // Verify CAPTCHA if required
                if (RequiresCaptcha(request))
                {
                    var captchaValid = await VerifyCaptcha(request.CaptchaToken);
                    
                    if (!captchaValid)
                    {
                        // Solve CAPTCHA automatically for trusted services
                        if (request.ServiceKey != null && IsValidServiceKey(request.ServiceKey))
                        {
                            var solution = await _captchaClient.SolveAsync(new SolveRequest
                            {
                                Type = CaptchaType.ReCaptchaV2,
                                SiteKey = Configuration["ReCaptcha:SiteKey"],
                                PageUrl = Request.GetDisplayUrl()
                            });
                            
                            request.CaptchaToken = solution.Solution;
                        }
                        else
                        {
                            return BadRequest(new { error = "Invalid CAPTCHA" });
                        }
                    }
                }
                
                // Process protected resource
                var resource = await _resourceService.GetResourceAsync(request.ResourceId);
                
                return Ok(new
                {
                    success = true,
                    data = resource,
                    timestamp = DateTime.UtcNow
                });
            }
            catch (Exception ex)
            {
                return StatusCode(500, new { error = ex.Message });
            }
        }
        
        private bool RequiresCaptcha(ResourceRequest request)
        {
            // Implement your logic
            return request.ResourceType == "sensitive" || 
                   GetRequestCount(request.ClientId) > 10;
        }
    }
}

package main

import (
    "github.com/ai4cap/go-sdk"
    "sync"
    "log"
)

type BatchProcessor struct {
    client      *ai4cap.Client
    workerPool  chan struct{}
    results     chan Result
}

type Result struct {
    ID       string
    Solution string
    Error    error
}

func NewBatchProcessor(apiKey string, workers int) *BatchProcessor {
    return &BatchProcessor{
        client:     ai4cap.NewClient(apiKey),
        workerPool: make(chan struct{}, workers),
        results:    make(chan Result, 100),
    }
}

func (bp *BatchProcessor) ProcessBatch(captchas []CaptchaTask) []Result {
    var wg sync.WaitGroup
    results := make([]Result, 0, len(captchas))
    
    // Start result collector
    go func() {
        for result := range bp.results {
            results = append(results, result)
        }
    }()
    
    // Process captchas concurrently
    for _, captcha := range captchas {
        wg.Add(1)
        
        go func(task CaptchaTask) {
            defer wg.Done()
            
            // Acquire worker slot
            bp.workerPool <- struct{}{}
            defer func() { <-bp.workerPool }()
            
            // Solve CAPTCHA
            solution, err := bp.solveCaptcha(task)
            
            bp.results <- Result{
                ID:       task.ID,
                Solution: solution,
                Error:    err,
            }
        }(captcha)
    }
    
    wg.Wait()
    close(bp.results)
    
    return results
}

func (bp *BatchProcessor) solveCaptcha(task CaptchaTask) (string, error) {
    request := &ai4cap.SolveRequest{
        Type: task.Type,
    }
    
    switch task.Type {
    case "image":
        request.Image = task.ImageData
    case "recaptcha_v2":
        request.SiteKey = task.SiteKey
        request.PageURL = task.PageURL
    case "hcaptcha":
        request.SiteKey = task.SiteKey
        request.PageURL = task.PageURL
    }
    
    solution, err := bp.client.Solve(request)
    if err != nil {
        return "", err
    }
    
    return solution.Solution, nil
}

Error Handling & Best Practices

Robust Error Handling

# Robust error handling with retry logic
import time
from typing import Optional, Dict, Any
import logging

class CaptchaSolverWithRetry:
    def __init__(self, api_key: str, max_retries: int = 3):
        self.client = Client(api_key)
        self.max_retries = max_retries
        self.logger = logging.getLogger(__name__)
        
    def solve_with_retry(
        self, 
        captcha_params: Dict[str, Any],
        retry_delay: float = 2.0
    ) -> Optional[str]:
        """Solve CAPTCHA with automatic retry on failure"""
        
        last_error = None
        
        for attempt in range(self.max_retries):
            try:
                # Log attempt
                self.logger.info(f"Solving CAPTCHA (attempt {attempt + 1}/{self.max_retries})")
                
                # Submit CAPTCHA
                result = self.client.solve(captcha_params)
                
                # Validate solution
                if self.validate_solution(result):
                    self.logger.info("CAPTCHA solved successfully")
                    return result['solution']
                else:
                    raise ValueError("Invalid solution format")
                    
            except RateLimitError as e:
                # Handle rate limiting
                self.logger.warning(f"Rate limited: {e}")
                wait_time = e.retry_after or (retry_delay * (2 ** attempt))
                time.sleep(wait_time)
                
            except NetworkError as e:
                # Handle network issues
                self.logger.error(f"Network error: {e}")
                last_error = e
                time.sleep(retry_delay)
                
            except InsufficientBalanceError as e:
                # Handle billing issues
                self.logger.error(f"Insufficient balance: {e}")
                self.notify_admin("Low balance alert", str(e))
                raise
                
            except Exception as e:
                # Handle unexpected errors
                self.logger.error(f"Unexpected error: {e}")
                last_error = e
                
                if attempt < self.max_retries - 1:
                    time.sleep(retry_delay)
        
        # All retries failed
        self.logger.error(f"Failed to solve CAPTCHA after {self.max_retries} attempts")
        raise last_error or Exception("Max retries exceeded")

Performance Monitoring

// Performance monitoring and alerting
const prometheus = require('prom-client');

class CaptchaMetrics {
  constructor() {
    // Define metrics
    this.solveDuration = new prometheus.Histogram({
      name: 'captcha_solve_duration_seconds',
      help: 'Duration of CAPTCHA solving in seconds',
      labelNames: ['type', 'status'],
      buckets: [0.1, 0.5, 1, 2, 5, 10, 30]
    });
    
    this.solveCounter = new prometheus.Counter({
      name: 'captcha_solve_total',
      help: 'Total number of CAPTCHA solve attempts',
      labelNames: ['type', 'status']
    });
    
    this.balanceGauge = new prometheus.Gauge({
      name: 'captcha_account_balance',
      help: 'Current account balance'
    });
    
    this.errorRate = new prometheus.Counter({
      name: 'captcha_errors_total',
      help: 'Total number of CAPTCHA solving errors',
      labelNames: ['type', 'error_type']
    });
  }
  
  async trackSolve(captchaType, solveFunction) {
    const timer = this.solveDuration.startTimer({ type: captchaType });
    
    try {
      const result = await solveFunction();
      
      timer({ status: 'success' });
      this.solveCounter.inc({ type: captchaType, status: 'success' });
      
      return result;
      
    } catch (error) {
      timer({ status: 'error' });
      this.solveCounter.inc({ type: captchaType, status: 'error' });
      this.errorRate.inc({ 
        type: captchaType, 
        error_type: error.constructor.name 
      });
      
      throw error;
    }
  }
  
  updateBalance(balance) {
    this.balanceGauge.set(balance);
    
    // Alert if balance is low
    if (balance < 10) {
      this.sendAlert('Low balance warning', `Balance: $${balance}`);
    }
  }
}

Integration Best Practices

Use environment variables for API keys
Implement retry logic with exponential backoff
Cache solutions when appropriate
Monitor usage and set up alerts

Handle rate limits gracefully
Validate solutions before use
Log errors for debugging
Test thoroughly in staging

Common Issues & Solutions

Issue	Cause	Solution
401 Unauthorized	Invalid API key	Verify API key in dashboard
402 Payment Required	Insufficient balance	Add credits to account
429 Too Many Requests	Rate limit exceeded	Implement request throttling
Timeout errors	Network issues or complex CAPTCHA	Increase timeout, retry request
Invalid solution	CAPTCHA expired or changed	Refresh and retry solving

Testing & Deployment

Development

• Use test API keys
• Mock CAPTCHA responses
• Test error scenarios
• Verify timeout handling
• Check memory usage

Staging

• Use production API
• Test with real CAPTCHAs
• Monitor performance
• Validate billing
• Load testing

Production

• Enable monitoring
• Set up alerts
• Configure auto-scaling
• Regular key rotation
• Backup strategies

Start Your Integration

Integrating AI4CAP.COM into your application is straightforward with our comprehensive SDKs and documentation. Whether you're building a web scraper, automating forms, or protecting your own services, our API provides reliable CAPTCHA solving that scales with your needs.

Follow this guide to implement a robust integration that handles errors gracefully, monitors performance, and provides a seamless experience for your users. With proper implementation, you can focus on your core business logic while we handle the complexity of CAPTCHA solving.

Get Your API Key - $15 Free View API Documentation

Related Resources

Documentation

How to Integrate CAPTCHA Solver API: Complete Guide

Quick Start: 5 Steps to Integration

Language-Specific Integration

Python Integration

JavaScript/Node.js Integration

Common Integration Patterns

Error Handling & Best Practices

Robust Error Handling

Performance Monitoring

Integration Best Practices

Common Issues & Solutions

Testing & Deployment

Development

Staging

Production

Start Your Integration

Related Resources

API Reference

Code Examples

GitHub SDKs

How to Integrate CAPTCHA Solver API: Complete Guide

.css-cuv99z{width:1em;height:1em;display:inline-block;line-height:1em;-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;color:currentColor;margin-right:var(--chakra-space-2);}Quick Start: 5 Steps to Integration

Language-Specific Integration

Python Integration

JavaScript/Node.js Integration

Common Integration Patterns

Form Automation

API Backend Integration

Batch Processing

Error Handling & Best Practices

Robust Error Handling

Performance Monitoring

Integration Best Practices

Common Issues & Solutions

Testing & Deployment

Development

Staging

Production

Start Your Integration

Related Resources

API Reference

Code Examples

GitHub SDKs

Quick Start: 5 Steps to Integration