---
title: "自分のキャラの名前・声・表情ごとの画像・立ち絵の種類を直す"
method: PATCH
path: "/api/v1/agent/characters/{characterId}"
tags: ["characters"]
---

# 自分のキャラの名前・声・表情ごとの画像・立ち絵の種類を直す

`PATCH /api/v1/agent/characters/{characterId}`

## Request

- Base URL: `https://app.yukkurigen.com`
- URL: `https://app.yukkurigen.com/api/v1/agent/characters/{characterId}`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

## Path parameters

- `characterId` string, required

## Request body

- object: どれか1つ以上。speakerId と voiceOf は同時に渡さない
  - `name` string
  - `speakerId` integer
  - `voiceOf` 'reimu' | 'marisa' | 'zundamon' | 'metan' | 'tsumugi' | 'anko'
  - `emotionImages` object: 表情ごとの画像の url。null でその表情の画像を外す
    - `joy` string, nullable
    - `excited` string, nullable
    - `surprise` string, nullable
    - `shocked` string, nullable
    - `sad` string, nullable
    - `crying` string, nullable
    - `angry` string, nullable
    - `troubled` string, nullable
    - `thinking` string, nullable
    - `confused` string, nullable
    - `doubtful` string, nullable
    - `smug` string, nullable
    - `embarrassed` string, nullable
    - `relaxed` string, nullable
    - `explaining` string, nullable
    - `love` string, nullable
  - `figure` 'full' | 'bust', nullable: null で指定を外す
  - `voice` LineVoice: 行の voice（声の速さ・高さ。その行だけ）。自作キャラの既定の voice も同じ形。
    - `speed` number: 話す速さ（1 が標準）
    - `pitch` number: 声の高さ（0 が標準）
  - `face` object, nullable: 顔の中心（立ち絵の通常の絵の中の 0〜1。左上 0,0・右下 1,1。目の上端と口の下端の真ん中あたり）。カメラが話者に寄る（行の camera・cameraMode dynamic）ときに画面の真ん中に持ってくる所。null で外す（描くたびに絵から推し量る）。顔が真ん中より下に映ったら y を大きく、上なら小さく
    - `x` number, required
    - `y` number, required
  - `defaultScale` number: 立ち絵の大きさ（0.5〜2。既定 1。足元を支点に）

## Response `200`

直したあとのキャラ（note に注意書き）

- CustomCharacter: 自分のキャラ（create_character / update_character / GET の 200）。characterId を create_yukkuri_video・update_lines の speaker に書く
  - `characterId` string, required: 話者 id（20文字の英数字）。list_characters の custom:true の id と同じ
  - `name` string, required
  - `kind` 'png' | 'psd', required: png=画像1枚（表情ごとの画像を update_character で足せる）/ psd=PSD から取り込んだ部品を重ねて描くキャラ（表情・口は画面で）
  - `imageUrl` string, nullable: 立ち絵（通常の顔）の url
  - `voice` object, nullable
    - `speakerId` integer
    - `engine` 'voicevox' | 'AquesTalk'
    - `label` string
    - `speed` number: 既定の話す速さ（標準の 1 なら無い）
    - `pitch` number: 既定の声の高さ（標準の 0 なら無い）
  - `emotionImages` object: 画像を設定した表情 → url（設定していない表情は近い表情か通常の顔で描かれる）
  - `figure` 'full' | 'bust', nullable
  - `face` object, nullable: 顔の中心（立ち絵の通常の絵の中の 0〜1。左上 0,0・右下 1,1。目の上端と口の下端の真ん中あたり）。カメラが話者に寄る（行の camera・cameraMode dynamic）ときに画面の真ん中に持ってくる所。null は保存していない（描くたびに絵から推し量る）
    - `x` number, required
    - `y` number, required
  - `defaultScale` number: 立ち絵の大きさ（0.5〜2。既定 1。枠に合わせた大きさに掛ける・足元を支点に）
  - `templates` string[], required: 出せるテンプレート（tohoku-ahiru-talk）

## Other responses

- `400`: 入力が正しくない・画像が使えない・PSD のキャラの表情（code: validation_error）
- `401`: 未認証（code: unauthenticated）
- `403`: 権限不足（projects:write / code: insufficient_scope）、またはほかの利用者の画像（code: forbidden）
- `404`: キャラが無い・ほかの利用者のもの（code: not_found）
- `429`: レート上限（code: rate_limited）
- `500`: サーバ側の失敗（code: internal_error）

## Changes

- **2026-10-20** `ba5f36b016da`: 30 warning, 18 info
  - added the new `already_subscribed` enum value to the `code` response property for the response status `400`
  - added the new `already_subscribed` enum value to the `code` response property for the response status `401`
  - added the new `already_subscribed` enum value to the `code` response property for the response status `403`
  - added the new `already_subscribed` enum value to the `code` response property for the response status `404`
  - …44 more

[Operation history](https://skmtc.dev/yukkurigen/apis/yukkurigen-ai-operated-api/changes/api/v1/agent/characters/:characterId/patch.md)

---

[API](https://skmtc.dev/yukkurigen/apis/yukkurigen-ai-operated-api.md) · [All operations](https://skmtc.dev/yukkurigen/apis/yukkurigen-ai-operated-api/llms.txt) · [OpenAPI document](https://skmtc.dev/yukkurigen/apis/yukkurigen-ai-operated-api/revisions/ba5f36b016da?raw)