PRODUCT TEST WORKSPACE

Grid Captcha

Captcha verification product

GRID

02 / REQUEST

Request preview

POST /api/validator/create.cgi

{
  "productCode" : "GRID",
  "adapter" : {
    "body" : "BASE64_CONTENT",
    "comment" : "Select all images containing stairs."
  }
}

03 / RESULT

Response example

EXAMPLE

Task ID —

{
  "code" : 0,
  "msg" : "Success",
  "data" : {
    "taskId" : "11111111-1111-4111-8111-111111111111",
    "productCode" : "GRID",
    "state" : "SUCCEEDED",
    "solution" : {
      "click" : [ 1, 5, 9 ]
    }
  }
}

Illustrative response; not a live task result. Replace all request placeholders before submitting.

Read data.solution after state becomes SUCCEEDED. The solution fields depend on the product; other states may return an empty object.

04 / API REFERENCE

Grid Captcha · API

For task creation and queries, send the API key in the apiKey HTTP header. JSON request bodies contain business parameters only.

Content-Type: application/json
apiKey: YOUR_API_KEY

Result and application

GRID_CELLS

Fallback only after confirming the matching native route unavailable. solution.click contains 1-based row-major tile numbers. Use current unchanged image/instructions and verify each subsequent round. Optional dimensions, instruction image and recognition settings do not make the result a native hCaptcha/reCAPTCHA token. previousId, when available, is an upstream ID, never a platform UUID. No fixed latency or target acceptance is guaranteed.

Conditional workflows

Browser image interaction BROWSER_INTERACTION

Requirements

GRID is a fallback only when no usable matching native product/integration exists, or diagnosis confirms that the native route cannot be used for this challenge. First inspect parameters, session bindings and expiry. HTTP 403, timeout or invalid input alone is not a fallback decision. GRID still requires a real current grid image, its original instructions and browser interaction capability; if those are unavailable, stop and report the blocker.
GRID has variable end-to-end latency from image capture, solver queue/recognition, polling and browser clicks; dynamic tiles and further rounds add work. It may exceed a short-lived target challenge deadline, so it is not the default for time-sensitive flows. No fixed solve time or target acceptance is guaranteed. Capture just before solving, check freshness again before applying, and discard answers after challenge expiry or image changes. Do not reuse expired answers or automatically create another paid task.
Collect fresh values from the same target/challenge. Respect product-specific hostname, action, challenge/session, IP, User-Agent and expiry requirements; these are not universally interchangeable. Apply returned cookies only to their matching domains.
Examples are placeholders, not runnable challenges. Documented result fields are not proof of target acceptance or a live availability test. Do not send unsupported fields.
SUCCEEDED means a solver result is available. Separately confirm that the target accepts the challenge and that the requested business operation completes. The solver cannot observe those two outcomes.

Input sources

Field	Input sources
`body`	Obtain the current challenge media from the target in the field format. For images, preserve original dimensions/order and crop to the challenge, not unrelated page content. For AUDIO, use the actual audio content.
`comment`	Use the actual question/instructions from the current challenge. Do not append agent commands such as Return coordinates. This field is semantically necessary for instruction-dependent tasks.
`rows`	Actual number of rows in the submitted current grid.
`columns`	Actual number of columns in the submitted current grid.
`imgInstructions`	Optional Base64 instruction image, at most 100 kB. Supply comment or imgInstructions; imgType requires the original English comment and original image files.
`imgType`	Optional upstream Computer Vision mode: recaptcha or funcaptcha. Do not label a generic/custom image as one of these types; original English comment and original image files are required.
`previousId`	Optional upstream task ID for the same continuing challenge, only if known. This is not a Nex Captcha platform UUID; omit when no upstream ID is available. Never use a different or expired challenge.
`minClicks`	Optional minClicks bound; cannot exceed rows*columns when dimensions are supplied. minClicks cannot exceed maxClicks.
`maxClicks`	Optional maxClicks bound; cannot exceed rows*columns when dimensions are supplied. minClicks cannot exceed maxClicks.
`canNoAnswer`	0 or 1. Set 1 only when the actual task permits no matching images; do not use it to hide recognition failures.

Request example

POST /api/validator/create.cgi · JSONC

{
  "productCode": "GRID", // Product code matching the adapter parameters.
  "adapter": { // Product-specific parameter object.
    "body": "BASE64_CONTENT", // Base64-encoded image or audio content.
    "comment": "Select all images containing stairs.", // Question or instructions for solving the challenge.
    "rows": 3, // Actual number of rows in the submitted current grid.
    "columns": 3, // Actual number of columns in the submitted current grid.
    "imgType": "recaptcha", // Optional upstream Computer Vision mode: recaptcha or funcaptcha. Do not label a generic/custom image as one of these types; original English comment and original image files are required.
    "previousId": "123456789", // Optional upstream task ID for the same continuing challenge, only if known. This is not a Nex Captcha platform UUID; omit when no upstream ID is available. Never use a different or expired challenge.
    "minClicks": 1, // Optional minClicks bound; cannot exceed rows*columns when dimensions are supplied. minClicks cannot exceed maxClicks.
    "maxClicks": 9, // Optional maxClicks bound; cannot exceed rows*columns when dimensions are supplied. minClicks cannot exceed maxClicks.
    "canNoAnswer": 0 // 0 or 1. Set 1 only when the actual task permits no matching images; do not use it to hide recognition failures.
  }
}

Request headers: apiKey: YOUR_API_KEY

Comments explain the fields. Copy produces valid JSON without comments.

Response example

POST /api/validator/query.cgi · JSONC

{
  "code": 0, // Business result code: 0 means success; other values indicate an error.
  "msg": "Success", // Result message; may be empty on success.
  "data": { // Response data; may be null on an error.
    "taskId": "11111111-1111-4111-8111-111111111111", // Task ID returned by task creation.
    "productCode": "GRID", // Product code matching the adapter parameters.
    "state": "SUCCEEDED", // Task state: CREATED, SUBMITTING, PROCESSING, SUCCEEDED, FAILED or EXPIRED.
    "solution": { // Product answer when SUCCEEDED; empty while processing or on failure.
      "click": [ // Grid cell numbers to click.
        1, // Product-specific answer field; use it according to the target website verification protocol.
        5, // Product-specific answer field; use it according to the target website verification protocol.
        9 // Product-specific answer field; use it according to the target website verification protocol.
      ]
    }
  }
}

Creating a task returns its ID and initial state. Query the result or use WebSocket to receive the completed answer shown below.

Request parameters

Field	Type	Required	Description
`productCode`	string	Yes	Product code matching the adapter parameters.
`adapter`	object	Yes	Product-specific parameter object.
`adapter.body`	string	Yes	Base64-encoded image or audio content.
`adapter.comment`	string	Conditional	Question or instructions for solving the challenge.
`adapter.rows`	integer	No	Actual number of rows in the submitted current grid.
`adapter.columns`	integer	No	Actual number of columns in the submitted current grid.
`adapter.imgInstructions`	string	Conditional	Optional Base64 instruction image, at most 100 kB. Supply comment or imgInstructions; imgType requires the original English comment and original image files.
`adapter.imgType`	string	No	Optional upstream Computer Vision mode: recaptcha or funcaptcha. Do not label a generic/custom image as one of these types; original English comment and original image files are required.
`adapter.previousId`	string	No	Optional upstream task ID for the same continuing challenge, only if known. This is not a Nex Captcha platform UUID; omit when no upstream ID is available. Never use a different or expired challenge.
`adapter.minClicks`	integer	No	Optional minClicks bound; cannot exceed rows*columns when dimensions are supplied. minClicks cannot exceed maxClicks.
`adapter.maxClicks`	integer	No	Optional maxClicks bound; cannot exceed rows*columns when dimensions are supplied. minClicks cannot exceed maxClicks.
`adapter.canNoAnswer`	integer	No	0 or 1. Set 1 only when the actual task permits no matching images; do not use it to hide recognition failures.

Response parameters

Field	Type	Description
`code`	integer	Business result code: 0 means success; other values indicate an error.
`msg`	string	Result message; may be empty on success.
`data`	object \| null	Response data; may be null on an error.
`data.taskId`	string	Task ID returned by task creation.
`data.productCode`	string	Product code matching the adapter parameters.
`data.state`	string	Task state: CREATED, SUBMITTING, PROCESSING, SUCCEEDED, FAILED or EXPIRED.
`data.solution`	object	Product answer when SUCCEEDED; empty while processing or on failure.
`data.failure`	object \| omitted	Public diagnosis for FAILED/EXPIRED only; no raw provider messages. Follow the failure handling guide.
`data.failure.code`	string	Failure code
`data.failure.nextAction`	string	Next action
`data.solution.click`	array	Grid cell numbers to click.
`data.solution.click[]`	integer	Product-specific answer field; use it according to the target website verification protocol.

Responses

HTTP business responses contain code, msg and data; code 0 means success. WebSocket uses a separate message structure.

-1317: Invalid API key.
-1100 / -1101: Invalid or missing request parameters.
-1401: Insufficient balance. Add funds before creating a task.
-1400 / -1001: System or task creation error.

API documentation

Grid Captcha

Create task

Request preview

Response example

Grid Captcha · API

Request example

Response example

Request parameters

Response parameters

Responses