---
title: "上げた画像から自分のキャラを作る"
method: POST
path: "/api/v1/agent/characters"
tags: ["characters"]
---

# 上げた画像から自分のキャラを作る

`POST /api/v1/agent/characters`

## Request

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

## Request body

- object: imageUrl か imageAssetId のどちらか1つ、speakerId か voiceOf のどちらか1つが必須
  - `name` string, required: キャラの名前（字幕の話者名にも出る）
  - `imageUrl` string: 立ち絵の画像の url（署名付きの url でもよい。保存は署名を落とした形）
  - `imageAssetId` string: 立ち絵の画像の assetId
  - `speakerId` integer: 声（GET /api/v1/voices の speakerId）
  - `voiceOf` 'reimu' | 'marisa' | 'zundamon' | 'metan' | 'tsumugi' | 'anko': 組み込みキャラと同じ声にする
  - `emotionImages` object: 表情ごとの画像の url（キーは script[].emotion と同じ16種）
    - `joy` string
    - `excited` string
    - `surprise` string
    - `shocked` string
    - `sad` string
    - `crying` string
    - `angry` string
    - `troubled` string
    - `thinking` string
    - `confused` string
    - `doubtful` string
    - `smug` string
    - `embarrassed` string
    - `relaxed` string
    - `explaining` string
    - `love` string
  - `figure` 'full' | 'bust': full=全身（字幕の上に収める）/ bust=上半身（画面の下端まで）。省略すると画面の下端まで
  - `voice` LineVoice: 行の voice（声の速さ・高さ。その行だけ）。自作キャラの既定の voice も同じ形。
    - `speed` number: 話す速さ（1 が標準）
    - `pitch` number: 声の高さ（0 が標準）
  - `face` object: 顔の中心（立ち絵の通常の絵の中の 0〜1。左上 0,0・右下 1,1。目の上端と口の下端の真ん中あたり）。カメラが話者に寄る（行の camera・cameraMode dynamic）ときに画面の真ん中に持ってくる所。省略すると絵から推し量って保存する（寄った画で顔が外れていたら PATCH で直す）
    - `x` number, required
    - `y` number, required
  - `defaultScale` number: 立ち絵の大きさ（省略すると 1）。枠に合わせた大きさに掛ける（足元を支点に。行の stage の scale とも掛け合わせる）

## Response `201`

作ったキャラ（nextStep に次の手順）

- 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`: 入力が正しくない・画像が使えない（code: validation_error）
- `401`: 未認証（code: unauthenticated）
- `403`: 権限不足（projects:write / code: insufficient_scope）、またはほかの利用者の画像（code: forbidden）
- `404`: imageAssetId の素材が無い・ほかの利用者のもの（code: not_found）
- `429`: レート上限（code: rate_limited。素材のアップロードと同じ枠）、またはストレージ容量の上限（code: quota_exceeded）
- `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/post.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)