reCAPTCHA Configuration

All image and video generation requires reCAPTCHA verification. The SDK supports 7 providers with automatic retry and fallback chains.

Recommended Providers

Chrome — Real Chrome browser, persistent context, highest reCAPTCHA scores
YesCaptcha — Reliable cloud-based solving, no local browser needed

Other providers: Playwright, Regotcha, CapSolver, Veo3Solver, Custom (self-hosted)

Why reCAPTCHA?

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

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

Supported Providers

Chrome (Recommended)

Uses a real Chrome browser with persistent context via Chrome DevTools Protocol. Achieves the highest reCAPTCHA scores by maintaining a real browser session.

const client = new GLabsClient({
  bearerToken: 'your-token',
  recaptcha: {
    provider: 'chrome',
    chromeOptions: {
      headless: false,     // headed mode = higher scores (default: false)
      projectId: 'your-project-id',
      maxRetries: 3,
      timeout: 30000,
      userDataDir: '~/.glabs-sdk/chrome-profile',
    },
  },
});

Why Chrome?

Persistent browser context — maintains cookies and session across requests
Real Chrome fingerprint — highest reCAPTCHA v3 scores
No external API dependency — runs locally
Auto-cleanup via client.close()

YesCaptcha (Recommended)

YesCaptcha is a reliable cloud-based 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)
  },
});

Why YesCaptcha?

No local browser required
Consistent success rates
Simple setup

Playwright

Uses a Playwright-managed browser to generate reCAPTCHA tokens locally.

const client = new GLabsClient({
  bearerToken: 'your-token',
  recaptcha: {
    provider: 'playwright',
    playwrightOptions: {
      headless: false,
      projectId: 'your-project-id',
      maxRetries: 3,
      timeout: 30000,
    },
  },
});

Requires playwright as a peer dependency: npm install playwright

Regotcha

Regotcha is optimized for Google Labs reCAPTCHA v3 Enterprise.

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

CapSolver

CapSolver provides 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',
    maxRetries: 30,
  },
});

CapSolver returns additional browser fingerprint data (userAgent, secChUa) that the SDK automatically includes in requests.

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

Option	Type	Required	Description
`provider`	`'chrome' \| 'yescaptcha' \| 'playwright' \| 'regotcha' \| 'capsolver' \| 'veo3solver' \| 'custom'`	Yes	The captcha solving service to use
`apiKey`	`string`	Yes*	API key for the provider (*not required for custom/veo3solver)
`jwtToken`	`string`	No**	JWT token for authentication (**required for veo3solver)
`customEndpoint`	`string`	No***	Custom solver endpoint URL (***required for custom provider)
`staticToken`	`string`	No	Static token to use directly (bypasses provider, useful for testing)
`proxy`	`string`	No	Proxy URL (CapSolver and Custom only)
`anchor`	`string`	No	Anchor parameter (Custom only)
`reload`	`string`	No	Reload parameter (Custom only)
`maxRetries`	`number`	No	Maximum polling attempts
`playwrightOptions`	`object`	No	Playwright browser config
`chromeOptions`	`object`	No	Chrome browser config
`fallback`	`RecaptchaConfig`	No	Fallback provider config

How It Works

Token Request Flow

SDK creates a task with the provider
Provider solves the reCAPTCHA challenge
SDK polls for the result
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:

Detecting the evaluation failure response
Requesting a new token from your provider
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:

Chrome (Recommended): Free — runs locally, no API costs
YesCaptcha (Recommended): Check pricing at yescaptcha.com
Regotcha: Check pricing at regotcha.com
CapSolver: Check pricing at capsolver.com

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.

reCAPTCHA Configuration

On this page