Skip to main content

Using a V2 custom model (Cubism 4+)

This page is for V2 (Cubism 4+ / 5) models only. Older models like 22 / 33 / Pio / Tia run on V1 and don't require payment — see Two ways to use V1 models.

1. Pay first​

V2 runs the Live2D Cubism 4+ Web SDK loader. Live2D Inc. requires third-party extensibility apps that use Cubism 4+ to sign a commercial agreement. The author of this project has signed a long-term agreement and distributes the official Cubism Core under that agreement, so this pipeline carries a one-time license fee per site.

  1. Register and pay on www.live2dweb.com.
  2. Stay signed in to the WordPress admin so the plugin can verify the license against live2dweb.com.

Without payment / without login, the Custom option of "Workshop API type" is disabled.

2. Prepare the V2 model files​

V2 models are exported by Cubism 4+. The manifest is *.model3.json, the body is *.moc3, plus textures, motions, expressions, etc.

Manifest requirements​

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

Where to host the model? (in order of preference)​

  1. Object storage + anti-hotlink (recommended; built-in license protection): Aliyun OSS, Tencent COS, Upyun, Qiniu, etc. Enable a Referer whitelist to allow only your site; if you put a CDN in front, make sure the anti-hotlink rules carry over.
  2. "Host on this site" via the plugin: after filling in modelAPI, choose "Custom new-version model · Host on this site" under "API type". The plugin downloads everything to wp-content/plugins/live-2d/model/ and only exposes a temporary signed URL to the front-end. See V2 anti-hotlink.
  3. The plugin's own model folder: drop wp-content/plugins/live-2d/model/{name}/{name}.model3.json directly. Simplest, but you control bandwidth yourself.
  4. Public static hosting like GitHub Pages / jsDelivr: it works, but not recommended in mainland China — speed is unstable and there's no anti-hotlink.

3. Fill in modelAPI in the admin​

WordPress admin → Live2D settings → Workshop API type → Custom. Below appear modelAPI and modelDir. The detailed rules for both fields are in How to fill in modelAPI / modelDir.

4. Texture (material) size​

Keep each texture under 2048×2048. Cubism 4+ textures are already sizeable; stacking several oversized PNGs easily pushes first-paint to 5–10 seconds. If the model exports textures beyond that, use Cubism Editor's "Embed texture atlas → Reassign size".

5. Advanced: super-sampling (V2 only)​

Plugin 2.1.3 added the super-sampling feature, which makes textures sharper on high-DPI displays. It only applies to V2 (model3.json) models — V1 ignores the toggle.

6. Security / copyright notes​

  1. You are responsible for the copyright of your own models. Best practice: upload to object storage with anti-hotlink + CORS limited to your origin.
  2. The workshop currently does not allow user uploads — we have no way to protect every uploader's copyright.
  3. Don't write your OSS SecretKey into the WordPress settings page. If you really need private-read + signed URLs, use environment variables in wp-config.php (see the FAQ on the anti-hotlink page).