# tianai-captcha builds slider and click captchas in Java

> tianai-captcha is a Java library for behaviour style captchas, covering slider, rotate, slide to restore and click to select, with a Spring Boot starter, a YAML configuration block and a browser SDK. It generates and validates the captcha data and leaves the second verification, and the risk decisions, to you.

**dromara/tianai-captcha** — captcha captcha captcha 可能是java界最好的开源行为验证码  [滑块验证码、点选验证码、行为验证码、旋转验证码， 滑动验证码]

- Repository: https://github.com/dromara/tianai-captcha
- Stars: 1,291 · Forks: 167
- Language: Java
- License: Apache-2.0
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/dromara-tianai-captcha

## Four captcha shapes, all behind one Java API

tianai-captcha is a Java implementation of behaviour style captchas, published under the Dromara organisation and distributed as tianai-captcha, tianai-captcha-springboot-starter and tianai-captcha-web-sdk. The supported captcha types are listed in the documentation: the slider captcha, the rotate captcha, the slide to restore captcha, and the character click captcha, where the user has to click specific characters in an image.

Those four are worth distinguishing, because they are not variations on one mechanism. A slider asks the user to move a cut out piece to a position, and the answer is judged against a target position plus the movement itself. A rotate captcha asks the user to rotate the image until it is upright. Slide to restore asks the user to slide a piece back into a gap, which is the same family as the slider but with the image reconstructed. The click captcha asks the user to click a sequence of characters named in a prompt.

The reason they are grouped as behaviour captchas is that the verification is not only the answer. The slider case shows it: the ImageCaptchaTrack parameter contains the slide trajectory and the timing data, and it is sent by the front end and used when the answer is checked. A bot that solves the image position without the human movement pattern gives the library a different signal to work with.

The audience is Java developers building a login, a registration or a sensitive form who want a captcha that runs inside their own application, with images, templates and rules they can change, and who would rather not send traffic to a hosted captcha vendor.

## Generation returns an id, verification takes the id and the track

The API shape is small and the same for every captcha type. You generate a captcha, you keep the id it returns, the front end solves it, and the front end sends the id and the solving data back, and you ask the library whether it matches.

In the Spring Boot setup the injected object is ImageCaptchaApplication. The generation call passes a type constant, for example CaptchaTypeConstant.SLIDER, and returns an ApiResponse holding an ImageCaptchaVO. The matching call takes that id and an ImageCaptchaTrack, and returns an ApiResponse whose success flag tells you whether the answer was right. The track is the object the front end fills in, and the code comments are explicit that it carries the sliding trajectory and the sliding time, and that it is passed in by the front end.

That is the whole contract, and it is worth being clear about where the trust boundary sits. The library is given a track produced by the client. A determined client can send anything. What the library does is compare the answer with the server side data it generated, and check the movement data it was given.

The documentation is explicit about the limit of the library here, in a comment on the non Spring example: the project is only responsible for generating and validating captcha data, and secondary verification has to be extended by the application. The example shows what a minimal extension looks like. After a successful match, the application generates a UUID token, stores it in a cache store with a five minute lifetime, and returns it to the client, and the next request carries the token so the backend can check it. That token is yours to design, and it is where you decide what a passed captcha is worth.

## The Spring Boot starter is a dependency and a YAML block

For a Spring Boot project, the starter is added as a Maven dependency:

```xml
<dependency>
    <groupId>cloud.tianai.captcha</groupId>
    <artifactId>tianai-captcha-springboot-starter</artifactId>
    <version>1.5.5</version>
</dependency>
```

The configuration lives under the captcha key in the application configuration file, and the comments point at the class cloud.tianai.captcha.autoconfiguration.ImageCaptchaProperties for the full set of options. The block that matters most is the cache and expiry settings:

```yaml
captcha:
  prefix: captcha
  expire:
    default: 10000
    WORD_IMAGE_CLICK: 20000
  init-default-resource: false
  local-cache-enabled: true
  local-cache-size: 20
  local-cache-wait-time: 5000
  local-cache-period: 2000
```

Three things in there are worth understanding. The prefix is the key prefix used when the captcha data is stored in Redis, and the documentation says the slider data goes to Redis automatically if your project already uses Redis, with a default key prefix of captcha:slider. The expiry values are in milliseconds, and the documentation explains why the click captcha gets a longer one, at 20000, because verifying a click captcha takes longer and a tighter expiry would expire the challenge while the user is still working on it. The local cache settings control a cache of pre-generated captcha data, twenty entries by default, with a five second wait after a failed fetch and a two second check interval.

The secondary verification block is off by default, and when enabled it carries its own expiry of 120000 milliseconds and its own key prefix of captcha:secondary, separate from the main captcha data.

One inconsistency in the documentation is worth flagging before you plan an upgrade: the Spring Boot starter is shown at version 1.5.5 while the plain artifact and the web SDK download are shown at 1.5.4, so the two halves of the integration are not documented at the same version.

## Without Spring, a builder assembles templates and background images

For a plain Java project the dependency is the core artifact, and the object that does the work is built explicitly with TACBuilder. The example assembles the application in a few lines:

```java
ImageCaptchaApplication application = TACBuilder.builder()
        .addDefaultTemplate()
        .addResource("SLIDER", new Resource("classpath", "META-INF/cut-image/resource/1.jpg"))
        .addResource("WORD_IMAGE_CLICK", new Resource("classpath", "META-INF/cut-image/resource/1.jpg"))
        .addResource("ROTATE", new Resource("classpath", "META-INF/cut-image/resource/1.jpg"))
        .build();
```

The builder takes a default template and then background resources per captcha type. The Resource constructor takes the kind of location first, classpath in this case, and the path second, and the documentation says the same mechanism also accepts file and url, so a background image can come from the classpath, from a file or from a URL. The slide captcha example uses a width and height of 600 by 360.

Generation and verification then follow the same shape as in the Spring version, with a CaptchaResponse of ImageCaptchaVO coming back from generateCaptcha for a type such as SLIDER, and a matching call that takes the id and a MatchParam built from the track.

The font configuration is the other thing that needs setting for the click captcha, since it renders characters. The YAML example points the font path at classpath:font/simhei.ttf, and the documentation notes that more than one font can be configured. If you do not set init-default-resource, which defaults to false, you are expected to supply your own resources.

## The browser side is a directory, a script tag and one config object

The front end is a packaged directory called tac that you host yourself, plus a load script. The documentation asks you to put the built tac directory into your project, and for Vue or React style projects into the public directory, or anywhere the browser can reach it, such as object storage. The download link given is a Gitee release tag for tianai-captcha-1.5.4.

The script itself is one tag:

```html
<script src="load.min.js"></script>
```

And for a web framework the documentation says to put that tag in public/index.html. The load script is hosted on a MinIO bucket, and you can download it and serve it locally instead.

Then you need a container element:

```html
<div id="captcha-box"></div>
```

And finally the config object, which is where the front end contract with your Java endpoints is defined. The required entries are requestCaptchaDataUrl, the generation endpoint, validCaptchaUrl, the check endpoint, bindEl, the div to mount into, and validSuccess, the callback that runs when the answer is accepted. The failure path is optional, and if you do not supply a validFail the default is used. There are also callbacks for the refresh button and the close button.

The init call takes the directory of the tac files, the config and a style object, and then init on the returned object displays the captcha:

```js
window.initTAC("./tac", config, style).then(tac => {
    tac.init();
}).catch(e => {
    console.log("初始化tac失败", e);
})
```

The style object is optional and carries a logoUrl you can leave null to remove the logo or point at your own image.

Browser support is listed as Chrome, Firefox, Safari, Opera, mainstream mobile browsers and embedded webviews on iOS and Android, and the framework support row covers H5, Angular, React, Vue2 and Vue3. The generation and check endpoints must match the default captcha interface specification of tianai-captcha, which is the constraint that ties the two halves together.

## What the library does not decide for you

There are two boundaries, and both are stated in the documentation rather than discovered later.

The first is that the project only generates and validates captcha data. Everything that turns a passed captcha into a permission, a token, a session, a risk score or a rate limit, is left to the application. The example code in the documentation shows the smallest possible version of that, a UUID stored in a cache with a five minute lifetime.

The second is the state store. In a Spring Boot deployment the captcha data goes to Redis automatically if the project already uses it, and the key prefix is configurable. Without Redis, you can enable a local cache, and it holds a fixed number of pre-generated captchas with a fetch and a check interval. Those are two quite different operational profiles, and the second one does not survive a restart, which is a real difference for a deployment with more than one instance.

The library is therefore the wrong tool in two situations. If you want a captcha service that also does risk scoring, device fingerprinting and rate limiting, this is only the captcha half of that product. And if your application is a single page app with a backend in another language, the Java library gives you nothing and the web SDK has no server to talk to.

A third limitation is the version line. The releases listed are 1.5.5 from 2026-02-28 and 1.5.1 from 2024-08-21, so the library is on a slow cadence, and the documented versions are not aligned between the starter, the core artifact and the web SDK download. A team that wants the front end and the back end on the same build has to check the three version numbers itself, because the documentation does not do it for them.

## Apache 2.0, a slow release line, and a community around it

The licence is Apache 2.0, in the LICENSE file at the repository root, which is a permissive licence with an express patent grant and no conditions on commercial use. For a component that sits in the path of every login attempt, that matters less than it does for a business critical library, but it removes one question from an adoption review.

The repository is not archived and the last push was on 2026-09-08, which is some six months after the newest release activity, but the release history itself is sparse. Version 1.5.5 is dated 2026-02-28 and version 1.5.1 is dated 2024-08-21, so there is a long gap between the two, and the 1.5.x line is where the project sits. The repository also contains a CLAUDE.md file at the root next to the readme, and the project is hosted with its releases on Gitee rather than only on the code hosting platform, which is worth knowing if you are following releases.

The structure of the repository mirrors the three ways you consume it. The tianai-captcha directory is the core library, tianai-captcha-springboot-starter is the auto configuration layer with the ImageCaptchaProperties class, and tianai-captcha-web-sdk is the browser package. There is a single pom.xml at the root, so the whole thing is one Maven build.

The maintenance conclusion is simple. This is a stable, small, well documented component with a permissive licence, an active but infrequent release line, and a live online demo and documentation site. If you adopt it, adopt it as a versioned dependency and pin the number, because the version strings in the documentation are not consistent with each other today.

## Conclusion

tianai-captcha is worth adopting if you run a Java backend that needs a captcha you control end to end, and you want the slider, rotate and click styles to be configurable in your own application rather than delegated to a hosted provider. It is the wrong choice if you want a finished risk engine, a rate limiter and a challenge decision in one package, because the project states that secondary verification is for you to extend. Before you add the dependency, decide where the captcha state will live, because the Spring Boot configuration stores it in Redis when your project already uses Redis and otherwise relies on the local cache, and read the two versions in the documentation apart, since the starter is published as 1.5.5 while the plain artifact and the web SDK download are still shown as 1.5.4.

## FAQ

### Which captcha types does tianai-captcha support?

The documentation lists four: the slider captcha (SLIDER), the rotate captcha (ROTATE), the slide to restore captcha (CONCAT) and the character click captcha (WORD_IMAGE_CLICK). Background resources are added per type with the builder, and the click type needs a font configured.

### How do I add tianai-captcha to a Spring Boot project?

Add the starter dependency cloud.tianai.captcha:tianai-captcha-springboot-starter, shown at version 1.5.5, then configure it under the captcha key in your application configuration file. The documented options include the Redis key prefix, the per type expiry in milliseconds, the local cache size and intervals, the font path, and the secondary verification block.

### What does the front end need to send back for a slider captcha?

The id returned by the generation call and an ImageCaptchaTrack, which the documentation describes as containing the sliding trajectory and the sliding time. You check the pair with the matching call and read the success flag of the returned ApiResponse.

### Does tianai-captcha handle the second verification after a captcha is solved?

No. The project states that it is only responsible for generating and validating captcha data, and that secondary verification must be extended by the application. The documented example generates a token, stores it in a cache store for five minutes and returns it to the client to send with the next request.

### How is the captcha data stored in a Spring Boot deployment?

The captcha data is stored in Redis automatically if the project already uses Redis, with a configurable key prefix and a default slider prefix of captcha:slider. Without Redis, you can enable a local cache of pre-generated captcha data, with a size of twenty entries by default and a five second wait after a failed fetch.

## Sources

- [dromara/tianai-captcha on GitHub](https://github.com/dromara/tianai-captcha)
- [Issues](https://github.com/dromara/tianai-captcha/issues)
- [License: Apache-2.0](https://github.com/dromara/tianai-captcha/blob/master/LICENSE)
- [README](https://github.com/dromara/tianai-captcha/blob/master/README.md)
- [Releases](https://github.com/dromara/tianai-captcha/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/dromara-tianai-captcha