{ "code": 0, "msg": "Success", "data": { "productCode": "GRID", "schema": { "type": "object", "description": "GRID input parameters. Read x-integration before creating a paid task. Fallback only when the matching native route is confirmed unavailable; latency and multiple rounds may exceed the target challenge deadline.", "required": [ "body" ], "properties": { "body": { "type": "string", "description": "Base64-encoded image or audio content.", "minLength": 1 }, "comment": { "type": "string", "description": "Question or instructions for solving the challenge.", "minLength": 1, "examples": [ "Select all images containing stairs." ] }, "rows": { "type": "integer", "description": "Actual number of rows in the submitted current grid.", "minimum": 1, "examples": [ 3 ] }, "columns": { "type": "integer", "description": "Actual number of columns in the submitted current grid.", "minimum": 1, "examples": [ 3 ] }, "imgInstructions": { "type": "string", "description": "Optional Base64 instruction image, at most 100 kB. Supply comment or imgInstructions; imgType requires the original English comment and original image files.", "minLength": 1, "examples": [ "BASE64_INSTRUCTION_IMAGE" ] }, "imgType": { "type": "string", "description": "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.", "enum": [ "recaptcha", "funcaptcha" ], "minLength": 1, "examples": [ "recaptcha" ] }, "previousId": { "type": "string", "description": "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.", "minLength": 1, "pattern": "^[0-9]+$", "examples": [ "123456789" ] }, "minClicks": { "type": "integer", "description": "Optional minClicks bound; cannot exceed rows*columns when dimensions are supplied. minClicks cannot exceed maxClicks.", "minimum": 0, "examples": [ 1 ] }, "maxClicks": { "type": "integer", "description": "Optional maxClicks bound; cannot exceed rows*columns when dimensions are supplied. minClicks cannot exceed maxClicks.", "minimum": 0, "examples": [ 9 ] }, "canNoAnswer": { "type": "integer", "description": "0 or 1. Set 1 only when the actual task permits no matching images; do not use it to hide recognition failures.", "enum": [ 0, 1 ], "examples": [ 0 ] } }, "additionalProperties": false, "anyOf": [ { "required": [ "comment" ] }, { "required": [ "imgInstructions" ] } ], "allOf": [ { "if": { "required": [ "imgType" ] }, "then": { "required": [ "comment" ] } } ] }, "example": { "body": "BASE64_CONTENT", "comment": "Select all images containing stairs." }, "integration": { "workflows": [ "BROWSER_INTERACTION" ], "readiness": "CONDITIONAL", "resultKind": "GRID_CELLS", "resultGuide": "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.", "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." ], "inputSources": { "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." }, "resultContract": "DOCUMENTED_FIELDS", "targetAcceptanceVerified": false, "indexBase": 1, "order": "ROW_MAJOR", "resultSchema": { "type": "object", "properties": { "click": { "type": "array", "items": { "type": "integer" } } }, "additionalProperties": true } }, "workflowGuide": { "title": "Choose an integration workflow", "rules": [ "Prefer the product-specific (native) CAPTCHA integration over generic GRID. Identify the actual product/version and read its schema/guide before choosing. Use HTTP_SUBMIT when the target supports it, otherwise BROWSER_RESULT when the browser can apply the native result. Image grids on screen do not by themselves mean the product is GRID. Collect real inputs; missing inputs are a blocker, not permission to guess.", "Apply a native result through the matching target integration: fill the expected token response field/callback, or use the returned challenge identifier and proof/answer fields together where that product requires them. Preserve the target session and bindings. Do not mix old and new challenge fields, replace only a picture, or assume the solver issues an unrelated transferable challenge/answer pair.", "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.", "Use the challenge and integration parameters issued by the target. A solver does not issue a freely transferable challenge/answer pair. Replacing a widget or image does not replace the server challenge.", "For MCP creation, retry with the same requestId and identical parameters. A changed challenge is a new task with a new requestId and another charge. Follow nextPollAfterSeconds; do not create tasks to poll. The REST creation body does not have a requestId field.", "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.", "For hCaptcha use enabled native HCAPTCHA, then get its schema. If absent from the current catalogue, report unavailable. Do not substitute RECAPTCHA_V2, IMPERVA, CUSTOM or GRID based on a checkbox or image grid. Check the native contract for the required target context before paying." ], "workflows": [ { "id": "HTTP_SUBMIT", "title": "HTTP submission", "precondition": "The target operation and challenge submission can be completed over HTTP with the same required session context. A solver HTTP API alone does not establish this.", "steps": "Obtain the target challenge and parameters; create and poll the matching solver task; submit the result with the target request; inspect target validation and business outcome." }, { "id": "BROWSER_RESULT", "title": "Apply a result in the browser", "precondition": "Your browser tool can read the required current integration parameters and apply this product result through the target integration. Browser capability is separate from solver capability.", "steps": "Read current native product parameters; solve; fill the expected token field/callback, or apply matching challenge identifier and proof/answer fields together as required; submit normally; inspect target validation and business outcome. Replacing an image alone is not integration." }, { "id": "BROWSER_INTERACTION", "title": "Browser image interaction", "precondition": "The current challenge matches the selected image product. Your browser tool can capture the correct image and execute the required clicks, rotation or drag actions.", "steps": "Capture the current challenge and original instructions; solve; map the answer to the current image; interact; inspect for replacement images or another round; verify the target outcome." } ], "completionStages": [ "SOLVER_SUCCEEDED", "CHALLENGE_ACCEPTED", "BUSINESS_COMPLETED" ], "stageNote": "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.", "failures": [ { "code": "INVALID_INPUT", "nextAction": "READ_PRODUCT_SCHEMA", "description": "Collect missing/correct inputs; do not retry unchanged invalid input or switch to GRID." }, { "code": "TRANSPORT_OR_WAF", "nextAction": "INSPECT_REQUEST_CHAIN", "description": "Inspect the HTTP/network/WAF response. A 403 is not a solver result; if delivery is uncertain, retry identical creation with the same requestId." }, { "code": "TASK_EXPIRED", "nextAction": "RECAPTURE_CHALLENGE", "description": "Check the current challenge and expiry. Only create a new paid task if still needed." }, { "code": "PROVIDER_INPUT_INVALID", "nextAction": "READ_PRODUCT_SCHEMA", "description": "The provider rejected input. Check the product, current parameters and instructions." }, { "code": "PROVIDER_UNSOLVABLE", "nextAction": "INSPECT_CHALLENGE", "description": "Inspect image quality/instructions and whether the challenge is current before deciding on another paid attempt." }, { "code": "PROVIDER_UNAVAILABLE", "nextAction": "RETRY_LATER", "description": "Service availability issue; do not change the CAPTCHA product solely for this reason." }, { "code": "TASK_FAILED", "nextAction": "INSPECT_CHALLENGE", "description": "No specific public cause is known. Report the task ID and inspect context; do not claim target rejection or infer an unsupported product." }, { "code": "TARGET_REJECTED", "nextAction": "CHECK_BINDING_AND_EXPIRY", "description": "Observed by the caller, not inferred from solver state. Check target response, challenge binding and expiry." }, { "code": "BROWSER_APPLICATION_UNSUPPORTED", "nextAction": "CHANGE_EXECUTION_ENVIRONMENT", "description": "The browser cannot apply the result. Report that capability limit instead of calling the solver product unavailable." } ], "labels": { "result": "Result and application", "requirements": "Requirements", "sources": "Input sources", "workflow": "Conditional workflows", "unknown": "Contract not yet documented", "failure": "Failure handling", "stages": "Solver success → target acceptance → business completion", "field": "Field", "failureCode": "Failure code", "failureObject": "Public diagnosis for FAILED/EXPIRED only; no raw provider messages. Follow the failure handling guide.", "action": "Next action" } } } }