API Reference

Base URL: https://api.billysbelovedbots.com

Notes:

• JSON field names use camelCase.
• int64 and uint64 values appear as JSON strings.
• Send image as a base64 string in JSON requests.

Services

Image-to-text solves

Submit static captcha images and get back a task ID for the solve.

Method	Path	Description
POST	/v1/image-to-text/tasks	Create image-to-text task

POST /v1/image-to-text/tasks

Name: Create image-to-text task

Create a new image-to-text task and return a task ID to poll for the plain-text result.

Request Body

Field	Type	Description
image	bytes (base64 string in JSON)	Raw captcha image bytes.<br><br>This request is for image-to-text captcha solves only. Accepted formats are PNG, JPG, WebP, and JPEG XL. GIF is not accepted. The maximum size is 100 KB and the maximum dimensions are 1000 by 1000 pixels. In JSON requests, send this field as a base64 string.

Response Body

Field	Type	Description
taskId	string	The unique task ID to poll with TaskService.GetTask.

Tasks and balance

Look up task status, list recent tasks, and read the current credit balance.

Method	Path	Description
GET	/v1/tasks/{task_id}	Get task
GET	/v1/tasks	List tasks
GET	/v1/balance	Get balance

GET /v1/tasks/{task_id}

Name: Get task

Fetch the latest state for a single task.

Path Parameters

Field	Type	Description
task_id	string	The task ID returned when the task was created.

Response Body

Field	Type	Description
taskId	string	The unique task ID.
kind	TaskKind	The task kind.
status	TaskStatus	The broad task state.
subcode	TaskSubcode	The detailed task state.
solution	string	The solved captcha text. Empty until the task completes successfully.
createdAt	RFC 3339 timestamp	When the task was created.
updatedAt	RFC 3339 timestamp	When the task state last changed.
solvedAt	RFC 3339 timestamp	When the task was solved successfully. Empty otherwise.

GET /v1/tasks

Name: List tasks

List recent tasks for the authenticated account.

Query Parameters

Field	Type	Description
pageSize	integer (int32)	Maximum number of tasks to return.<br><br>Defaults to 20 and is capped at 100.
pageToken	string	Cursor returned by a previous ListTasks response.
statusFilter	TaskStatus	Optional filter by broad task status.
kindFilter	TaskKind	Optional filter by task kind.

Response Body

Field	Type	Description
tasks	array<GetTaskResponse>	Tasks in newest-first order for the current page.
nextPageToken	string	Cursor for the next page. Empty when there are no more results.
totalCount	string (int64)	Total number of tasks that match the current filter.

GET /v1/balance

Name: Get balance

Return the current credit balance for the authenticated account.

Request

This endpoint takes no request parameters.

Response Body

Field	Type	Description
credits	string (int64)	Credits remaining. One credit pays for one solve attempt.

Schemas

Message: CreateImageToTextTaskRequest

Request body for a new image-to-text task.

Field	Type	Description
image	bytes (base64 string in JSON)	Raw captcha image bytes.<br><br>This request is for image-to-text captcha solves only. Accepted formats are PNG, JPG, WebP, and JPEG XL. GIF is not accepted. The maximum size is 100 KB and the maximum dimensions are 1000 by 1000 pixels. In JSON requests, send this field as a base64 string.

Message: CreateImageToTextTaskResponse

Response body for a new image-to-text task.

Field	Type	Description
taskId	string	The unique task ID to poll with TaskService.GetTask.

Message: GetTaskRequest

Request a single task by its ID.

Field	Type	Description
taskId	string	The task ID returned when the task was created.

Message: GetTaskResponse

The current server-side state for one task.

Field	Type	Description
taskId	string	The unique task ID.
kind	TaskKind	The task kind.
status	TaskStatus	The broad task state.
subcode	TaskSubcode	The detailed task state.
solution	string	The solved captcha text. Empty until the task completes successfully.
createdAt	RFC 3339 timestamp	When the task was created.
updatedAt	RFC 3339 timestamp	When the task state last changed.
solvedAt	RFC 3339 timestamp	When the task was solved successfully. Empty otherwise.

Message: ListTasksRequest

List recent tasks.

Field	Type	Description
pageSize	integer (int32)	Maximum number of tasks to return.<br><br>Defaults to 20 and is capped at 100.
pageToken	string	Cursor returned by a previous ListTasks response.
statusFilter	TaskStatus	Optional filter by broad task status.
kindFilter	TaskKind	Optional filter by task kind.

Message: ListTasksResponse

Page of task history.

Field	Type	Description
tasks	array<GetTaskResponse>	Tasks in newest-first order for the current page.
nextPageToken	string	Cursor for the next page. Empty when there are no more results.
totalCount	string (int64)	Total number of tasks that match the current filter.

Message: GetBalanceRequest

Empty request for a balance lookup.

This message has no fields.

Message: GetBalanceResponse

Current credit balance for the authenticated account.

Field	Type	Description
credits	string (int64)	Credits remaining. One credit pays for one solve attempt.

Enums

Enum: TaskStatus

Broad status categories for a task.

Value	Number	Description
TASK_STATUS_UNSPECIFIED	0	Zero value. Treat as “no filter” in requests.
TASK_STATUS_IN_PROGRESS	1	The task has been accepted but does not have a final answer yet.
TASK_STATUS_COMPLETED	2	The task finished successfully and solution is populated.
TASK_STATUS_FAILED	3	The task finished unsuccessfully.

Enum: TaskSubcode

Detailed subcodes providing granular task state.

These values are stable public API surface and are intended for programmatic retry, alerting, and analytics decisions.

Value	Number	Description
TASK_SUBCODE_UNSPECIFIED	0	Zero value. Treat as unknown or unset.
TASK_SUBCODE_QUEUED	1	The task has been created and is waiting to be processed.
TASK_SUBCODE_SOLVING	2	Work on the task is currently in progress.
TASK_SUBCODE_SOLVED	10	The captcha was solved successfully and solution is available.
TASK_SUBCODE_UNSOLVABLE	20	No confident solution could be produced for the captcha.
TASK_SUBCODE_TIMEOUT	21	The task did not finish before the timeout.
TASK_SUBCODE_INVALID_IMAGE	22	The uploaded image failed validation or normalization.
TASK_SUBCODE_INSUFFICIENT_CREDITS	23	The authenticated account did not have enough credits to create the task.
TASK_SUBCODE_INTERNAL_ERROR	24	An internal platform error prevented the task from completing.

Enum: TaskKind

The kind of task that was created.

Value	Number	Description
TASK_KIND_UNSPECIFIED	0	Zero value. Treat as “no filter” in requests.
TASK_KIND_IMAGE_TO_TEXT	1	Solve a static captcha image into plain text.