GLabs SDK

reCAPTCHA Configuration

Configure reCAPTCHA providers for image and video generation

reCAPTCHA Configuration

Both image and video generation require reCAPTCHA verification. The SDK supports five providers.

Recommended Providers

  • Regotcha - Best success rate for Google Labs, affordable pricing
  • CapSolver - High reliability with proxy support and browser fingerprinting

Other providers: YesCaptcha, Veo3Solver, Custom (self-hosted)

Why reCAPTCHA?

Google Labs uses reCAPTCHA v3 Enterprise to protect against abuse. The SDK handles this transparently:

  1. All generation requests require a reCAPTCHA token
  2. SDK automatically fetches a token before each request
  3. If token evaluation fails, SDK retries with a new token (up to 3 attempts)

Supported Providers

Regotcha offers the best success rate for Google Labs reCAPTCHA v3 Enterprise at competitive pricing.

const client = new GLabsClient({
  bearerToken: 'your-token',
  recaptcha: {
    provider: 'regotcha',
    apiKey: 'your-regotcha-api-key',
    maxRetries: 30, // Optional: max polling attempts (default: 30)
  },
});

Why Regotcha?

  • Optimized for Google Labs reCAPTCHA v3 Enterprise
  • Fast token generation (typically 5-15s)
  • Affordable pricing
  • Simple API with high reliability

CapSolver provides high reliability with advanced features like proxy support and browser fingerprinting.

const client = new GLabsClient({
  bearerToken: 'your-token',
  recaptcha: {
    provider: 'capsolver',
    apiKey: 'your-capsolver-api-key',
    proxy: 'http://user:pass@ip:port', // Optional: residential proxy
    maxRetries: 30, // Optional: max polling attempts (default: 30)
  },
});

Why CapSolver?

  • Supports residential proxy for improved success rates
  • Provides browser fingerprint data (userAgent, secChUa)
  • Established service with good documentation
  • Suitable for high-volume usage

YesCaptcha

YesCaptcha is a captcha solving service.

const client = new GLabsClient({
  bearerToken: 'your-token',
  recaptcha: {
    provider: 'yescaptcha',
    apiKey: 'your-yescaptcha-client-key',
    maxRetries: 20, // Optional: max polling attempts (default: 20)
  },
});

Veo3Solver

Veo3Solver is a token service that provides pre-solved reCAPTCHA tokens via JWT authentication.

const client = new GLabsClient({
  bearerToken: 'your-token',
  recaptcha: {
    provider: 'veo3solver',
    jwtToken: 'your-jwt-token',
  },
});

No polling required - tokens are returned immediately via a simple GET request.

Static Token (Testing)

For testing captcha services or debugging, you can pass a token directly without using any provider.

const client = new GLabsClient({
  bearerToken: 'your-token',
  recaptcha: {
    provider: 'regotcha', // Provider is required but ignored when staticToken is set
    staticToken: 'your-pre-obtained-token',
  },
});

This bypasses all provider logic and uses the provided token directly. Useful for:

  • Testing captcha provider tokens manually
  • Debugging API responses without waiting for token generation
  • Integration testing with known-good tokens

Custom Solver

Use your own self-hosted reCAPTCHA solver service.

const client = new GLabsClient({
  bearerToken: 'your-token',
  recaptcha: {
    provider: 'custom',
    customEndpoint: 'http://localhost:8000/solve',
    proxy: 'http://user:pass@host:port', // Optional
    anchor: 'PCFET0NUWVBFIEhUTUw...', // Optional
    reload: 'CiAgICAgICAgICAgIGZldGNo...', // Optional
  },
});

Custom Solver API Specification:

Your custom solver endpoint must implement a POST endpoint that accepts:

{
  "websiteURL": "https://labs.google",
  "websiteKey": "6LdsFiUsAAAAAIjVDZcuLhaHiDn5nnHVXVRQGeMV",
  "pageAction": "FLOW_GENERATION",
  "anchor": "...",     // Optional, base64 encoded
  "reload": "...",     // Optional, base64 encoded
  "proxy": "http://user:pass@host:port"  // Optional
}

And returns:

{
  "success": true,
  "token": "03AFcWeA..."
}

On error:

{
  "success": false,
  "error": "Error message"
}

Configuration Options

OptionTypeRequiredDescription
provider'yescaptcha' | 'capsolver' | 'regotcha' | 'veo3solver' | 'custom'YesThe captcha solving service to use
apiKeystringYes*API key for the provider (*not required for custom/veo3solver)
jwtTokenstringNo**JWT token for authentication (**required for veo3solver)
customEndpointstringNo***Custom solver endpoint URL (***required for custom provider)
staticTokenstringNoStatic token to use directly (bypasses provider, useful for testing)
proxystringNoProxy URL (CapSolver and Custom only)
anchorstringNoAnchor parameter (Custom only)
reloadstringNoReload parameter (Custom only)
maxRetriesnumberNoMaximum polling attempts

How It Works

Token Request Flow

  1. SDK creates a task with the provider
  2. Provider solves the reCAPTCHA challenge
  3. SDK polls for the result
  4. Token is included in API requests

Regotcha Flow

SDK -> Regotcha: createTask (ReCaptchaV3EnterpriseTaskProxyLess)
Regotcha -> SDK: taskId
SDK -> Regotcha: getTaskResult (polling every 2s)
Regotcha -> SDK: { gRecaptchaResponse: "token" }

CapSolver Flow

SDK -> CapSolver: createTask (ReCaptchaV3EnterpriseTask)
CapSolver -> SDK: taskId
SDK -> CapSolver: getTaskResult (polling every 2s)
CapSolver -> SDK: { gRecaptchaResponse: "token", userAgent, secChUa }

Browser Fingerprint

CapSolver provides additional browser fingerprint data:

  • userAgent: Browser user agent string
  • secChUa: Sec-CH-UA header value

The SDK automatically includes these headers in requests when available, improving success rates.

Using Proxies (CapSolver)

For better success rates, CapSolver supports residential proxies:

const client = new GLabsClient({
  bearerToken: 'your-token',
  recaptcha: {
    provider: 'capsolver',
    apiKey: 'your-api-key',
    proxy: 'http://username:[email protected]:8080',
  },
});

Proxy formats:

  • HTTP: http://user:pass@ip:port
  • SOCKS5: socks5://user:pass@ip:port

Automatic Retry on Evaluation Failure

Sometimes reCAPTCHA tokens are rejected by Google with "reCAPTCHA evaluation failed". The SDK automatically handles this by:

  1. Detecting the evaluation failure response
  2. Requesting a new token from your provider
  3. Retrying the request (up to 3 attempts by default)
[Image] Fetching reCAPTCHA token (attempt 1/3)...
[Image] reCAPTCHA token obtained, generating...
[Image] reCAPTCHA evaluation failed (attempt 1/3), retrying with new token...
[Image] Fetching reCAPTCHA token (attempt 2/3)...
[Image] reCAPTCHA token obtained, generating...
✓ Success

Without reCAPTCHA

Both image and video generation require reCAPTCHA configuration. Without it, requests will fail immediately:

// This will throw immediately
const client = new GLabsClient({
  bearerToken: 'your-token',
  // No recaptcha config - ERROR!
});
 
await client.images.generate({...});
// Error: reCAPTCHA configuration is required for image generation
 
await client.videos.generateTextToVideo({...});
// Error: reCAPTCHA configuration is required for video generation

Error Handling

import { GLabsError } from '@getvrex/glabs-sdk';
 
try {
  await client.videos.generateTextToVideo({...});
} catch (error) {
  if (error instanceof GLabsError) {
    switch (error.code) {
      case 'RECAPTCHA_REQUIRED':
        console.error('Configure reCAPTCHA in client options');
        break;
      case 'RECAPTCHA_EVAL_FAILED':
        console.error('Token evaluation failed after all retries');
        break;
      case 'RECAPTCHA_TIMEOUT':
        console.error('Token request timed out, try again');
        break;
      case 'RECAPTCHA_FAILED':
        console.error('Token request failed:', error.message);
        break;
      case 'RECAPTCHA_API_ERROR':
        console.error('Provider API error:', error.message);
        break;
    }
  }
}

Cost Considerations

All providers charge per solved captcha:

Each generation request requires a new token. If evaluation fails, the SDK will request additional tokens (up to 3 per request). Plan your budget accordingly.

Previous

Video Generation

Next

Tier Configuration

On this page