API Documentation

Captcha Solver API Docs

Complete API reference and integration guide for the Oyolo AI Captcha Solver

Authentication

All API requests require authentication using a Bearer token in the Authorization header.

Getting Your API Key

  1. Sign up for an account at oyola-ai
  2. Navigate to your dashboard
  3. Generate a new API key from the API Keys section
  4. Copy and securely store your API key
Authorization: Bearer YOUR_API_KEY

Security Best Practices

  • Never expose your API key in client-side code
  • Store API keys as environment variables
  • Rotate your API keys regularly
  • Use different keys for development and production

API Endpoints

Our REST API provides a simple endpoint for solving captchas.

POST /v1/captcha/solve

Submit a captcha image for solving. Supports multiple image formats including PNG, JPEG, GIF, and WebP.

Request Parameters

Parameter Type Required Description
image File Yes Captcha image file (multipart/form-data)
image_url String No URL of the captcha image (alternative to file upload)
image_base64 String No Base64-encoded image data (alternative to file upload)
type String No Captcha type hint: "image", "text", "recaptcha" (auto-detected if not provided)
GET /v1/captcha/status/:task_id

Check the status of a captcha solving task. Useful for async operations.

Path Parameters

Parameter Type Description
task_id String Task ID returned from the solve endpoint

Request & Response

Request Example

# cURL
curl -X POST https://api.oyolo.ai/v1/captcha/solve \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@captcha.png"

# With base64
curl -X POST https://api.oyolo.ai/v1/captcha/solve \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_base64": "iVBORw0KGgoAAAANSUhEUgAA..."}'

Success Response

{
  "success": true,
  "task_id": "task_abc123xyz",
  "solution": "A3B7K",
  "confidence": 0.98,
  "processing_time": 2.3,
  "timestamp": "2024-01-15T10:30:00Z"
}

Response Fields

Field Type Description
success Boolean Whether the request was successful
task_id String Unique identifier for this solving task
solution String The solved captcha text or answer
confidence Float Confidence score between 0 and 1
processing_time Float Time taken to solve in seconds
timestamp String ISO 8601 timestamp of the response

Code Examples

Integration examples in popular programming languages

Python

requests 
import requests
import os

def solve_captcha(image_path):
    url = "https://api.oyolo.ai/v1/captcha/solve"
    api_key = os.getenv("OYOLO_API_KEY")
    
    with open(image_path, 'rb') as f:
        files = {'image': f}
        headers = {'Authorization': f'Bearer {api_key}'}
        response = requests.post(url, files=files, headers=headers)
    
    return response.json()

# Usage
result = solve_captcha('captcha.png')
print(f"Solution: {result['solution']}")

JavaScript / Node.js

form-data 
const FormData = require('form-data');
const fs = require('fs');
const axios = require('axios');

async function solveCaptcha(imagePath) {
  const form = new FormData();
  form.append('image', fs.createReadStream(imagePath));
  
  const response = await axios.post(
    'https://api.oyolo.ai/v1/captcha/solve',
    form,
    {
      headers: {
        ...form.getHeaders(),
        'Authorization': `Bearer ${process.env.OYOLO_API_KEY}`
      }
    }
  );
  
  return response.data;
}

// Usage
solveCaptcha('captcha.png')
  .then(result => console.log(`Solution: ${result.solution}`));

cURL

bash 
curl -X POST https://api.oyolo.ai/v1/captcha/solve \
  -H "Authorization: Bearer $OYOLO_API_KEY" \
  -F "image=@captcha.png"

Error Handling

The API uses standard HTTP status codes and returns error details in JSON format. 

{
  "success": false,
  "error": "error_code",
  "message": "Human-readable error message",
  "details": {
    // Additional error details
  }
}

Error Codes

Status Code Error Code Description
400 invalid_request Invalid request parameters or missing required fields
401 unauthorized Invalid or missing API key
402 payment_required Account quota exceeded or payment required
413 file_too_large Image file exceeds maximum size (10MB)
415 unsupported_format Unsupported image format
429 rate_limit_exceeded Too many requests, rate limit exceeded
500 internal_error Internal server error
503 service_unavailable Service temporarily unavailable

Rate Limits

Rate limits are applied per API key to ensure fair usage and system stability.

Free
100
requests/day
Pro
10,000
requests/day
Enterprise
Unlimited
custom limits

Rate Limit Headers

Every API response includes rate limit information in the response headers: 

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9995
X-RateLimit-Reset: 1642233600

X-RateLimit-Limit: Maximum number of requests allowed per day

X-RateLimit-Remaining: Number of requests remaining in the current period

X-RateLimit-Reset: Unix timestamp when the rate limit resets

Ready to Get Started?

Start solving captchas automatically today. Free trial available - no credit card required.

Get API Access Contact Support