Skip to main content

How to fill in modelAPI / modelDir

In WordPress admin → Live2D settings → "Workshop API type" choose Custom, and two inputs appear:

  • modelAPI — a URL or URL prefix
  • modelDir — a list, one subdirectory name per line

How they combine is determined by the trailing character of modelAPI. There are only two valid forms.

Form ①: direct single-model link (modelAPI ends in .json)​

modelAPI is a complete *.model3.json URL. The modelDir list below is ignored.

Example

modelAPI:  https://cdn.example.com/live2d/haru/haru.model3.json
modelDir:  (leave empty; ignored)

The browser fetches that JSON directly. The "Previous / Next" switch buttons on the front-end are meaningless in this mode — disable them in the admin.

Form ②: directory root + multiple models (modelAPI ends in /)​

modelAPI is a root directory URL and modelDir lists multiple subdirectory names. The plugin assembles full URLs as {modelAPI}{name}/{name}.model3.json.

Key constraint: the *.model3.json filename inside each subdirectory must match the subdirectory name exactly.

Example

modelAPI:  https://cdn.example.com/live2d/

modelDir:
  - haru
  - mao
  - shizuku

At load time the plugin assembles:

https://cdn.example.com/live2d/haru/haru.model3.json
https://cdn.example.com/live2d/mao/mao.model3.json
https://cdn.example.com/live2d/shizuku/shizuku.model3.json

The "blink button / switch button" on the front-end will cycle through these models.

Which one should I pick?​

ScenarioRecommended form
Hosting a single fixed model, no switching① direct link
Want visitors to switch between multiple models② directory root + multiple modelDir
Want to use "Host on this site"② — in this mode the modelAPI input is hidden; only modelDir is filled

Path / protocol requirements​

  • The path must not contain non-ASCII / Chinese characters.
  • If your site is https, then modelAPI and every file it references (.moc3, textures, motion3.json, physics3.json, cdi3.json, …) must also be https, or the browser will fail with a mixed-content error.
  • Cross-origin: when hosting models on OSS / COS / your own CDN, enable CORS correctly (typically allow your site's domain as Origin).

What's different in the browser extension?​

The "Custom URL (paid)" mode in the browser extension uses the same modelAPI / modelDir rules as the WordPress plugin, except there is no "Host on this site" option. Make sure your source URL allows chrome-extension://... or * as Origin.