---
title: "自分のキャラの設定を読む"
method: GET
path: "/api/v1/agent/characters/{characterId}"
tags: ["characters"]
---

# 自分のキャラの設定を読む

`GET /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

## Response `200`

キャラの設定

- 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

- `401`: 未認証（code: unauthenticated）
- `403`: 権限不足（projects:read / code: insufficient_scope）
- `404`: キャラが無い・ほかの利用者のもの（code: not_found）
- `500`: サーバ側の失敗（code: internal_error）

## Changes

- **2026-10-20** `ba5f36b016da`: 20 warning, 12 info
  - 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`
  - added the new `already_subscribed` enum value to the `code` response property for the response status `500`
  - …28 more

[Operation history](https://skmtc.dev/yukkurigen/apis/yukkurigen-ai-operated-api/changes/api/v1/agent/characters/:characterId/get.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)