---
title: "指定した行だけ差し替える（update_lines）"
method: PATCH
path: "/api/v1/projects/{projectId}/lines"
tags: ["projects"]
---

# 指定した行だけ差し替える（update_lines）

`PATCH /api/v1/projects/{projectId}/lines`

## Request

- Base URL: `https://app.yukkurigen.com`
- URL: `https://app.yukkurigen.com/api/v1/projects/{projectId}/lines`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

## Path parameters

- `projectId` string, required

## Request body

- object
  - `edits` object[], required: 直す行だけを並べる。同じ index を2回書くと 400。
    - `index` integer, required: 行番号（get_project が返す index）
    - `text` string: 新しいセリフ本文（字幕に出る）。読み違えそうな漢字にはルビを書ける: ｜漢字《よみ》（｜は全角・半角どちらでも）——字幕は「漢字」、声は「よみ」。短く 漢字《よみ》 とも書ける（直前の漢字の並び全体に掛かる）。親文字・よみは50文字まで、改行と《》｜は入れない。完成していない記法はそのまま字幕に出る。読みは POST /api/v1/projects/{projectId}/readings/check で確かめる
    - `speaker` string: 話者id（/api/v1/characters 参照）
    - `emotion` 'joy' | 'excited' | 'surprise' | 'shocked' | 'sad' | 'crying' | 'angry' | 'troubled' | 'thinking' | 'confused' | 'doubtful' | 'smug' | 'embarrassed' | 'relaxed' | 'explaining' | 'love' | 'null', nullable: 表情（生成時の emotion と同じ16種）。null で通常の顔
    - `pose` 'normal' | 'point' | 'wave' | 'cheer' | 'hip' | 'think' | 'mouth_cover' | 'whisper' | 'shh' | 'chest' | 'mic' | 'cross_arms' | 'peace' | 'hold' | 'null', nullable: ポーズ（腕の形。生成時の pose と同じ）。null で表情の既定の腕。そのキャラに無いポーズは外す扱い
    - `reading` string, nullable: 行全体の読み仮名（未指定なら text を、ルビと読みの辞書を当てて読む）。書くとその行は辞書もルビも効かず、これをそのまま読む。2000文字まで（text と同じ上限）。本番 MP4 の見積もりは各行の text と reading の長いほうで数える。null で外す
    - `cameraMode` 'dynamic' | 'summary' | 'null', nullable: その行のカメラ（任意）。dynamic=背景ごと話者に寄る / summary=立ち絵を消す / null=寄らない。使うなら盛り上がり・オチの2〜4行まで（全行 dynamic だと寄りが効かなくなる）。null にした行が後から自動で寄ることはない。立ち絵が画面に出ている行にだけ効く。
    - `camera` LineCamera: 行ごとのカメラ（その行だけ）。
      - `zoom` number: 寄りの大きさ（1 は寄らない）
      - `target` union
        - string: "speaker"（その行の話者）か、台本で話すキャラの id
        - object: 画面の %（0〜100）の点
          - `x` number, required
          - `y` number, required
      - `center` boolean: 寄る先を画面の真ん中へ持ってくるか（既定 true）
      - `move` 'cut' | 'ease' | 'slow': 前の行のカメラからの移り方（既定 ease）
      - `shake` union: 行の頭で画面を揺らす（true は light）
        - boolean
        - 'light' | 'strong'
      - `materials` 'zoom' | 'fixed': その行の素材をカメラと一緒に寄せるか（省くとテンプレートの従来どおり）
    - `backgroundImageUrl` string, nullable: この行から背景を差し替える（場面転換）。null でこの行の指定を外す。https のみ。
    - `materialImageUrl` string, nullable: この行で画面に出す素材画像の URL。null で外す。https のみ。位置と大きさは materialBox。
    - `materialBox` object, nullable: その行の素材の位置と大きさ（画面に対する %、x/y は左上）。AI が行ごとに決めてよい。画像は枠に収まり、枠の上端・左右中央に出る。省略するとテンプレートの素材の枠。null でテンプレートの枠に戻す
      - `x` number, required
      - `y` number, required
      - `width` number, required
      - `height` number, required
    - `chapter` string, nullable: この行から始まる章の見出し（14文字以内が目安。30文字まで受け付け、16文字を超えた分は黙って切る。横長の左上に出る）。null で外す
    - `emphasis` union: 強調テロップ（その行だけ）。文字列（黄色・従来の場所）か、色と出す場所を書いたオブジェクト。
      - string
      - object
        - `text` string, required: 強調する言葉（10文字以内が目安、12文字で切る）
        - `color` 'yellow' | 'red' | 'blue' | 'green': 文字の色（既定 yellow）
        - `position` 'top' | 'center' | 'bottom': 出す高さ。top=画面の上の方 / center=真ん中 / bottom=字幕のすぐ上。省くと従来の高さ（横長は上から26%、縦型は24%。顔と顔の間）
        - `x` number: テロップの中心の横の位置（画面の幅の %）。省くと左右の真ん中。端ほど折り返す幅が狭くなる（20〜80 が無難）
        - `y` number: テロップの中心の縦の位置（画面の高さの %）。position より勝つ
    - `card` object, nullable: 図解カード（POST /agent/generate の card と同じ）。次の共有リンク作成かレンダーで画像になる。その行の前の素材は外れる。null で外す
      - `title` string, required
      - `items` string[]
      - `style` 'list' | 'steps' | 'point'
      - `span` integer
    - `photo` string[], nullable: 写真の英語の検索語（1〜3個）。次の共有リンク作成かレンダーで写真を探して入れる。null で外す
    - `effect` union: この行の頭で鳴らす効果音。組み込みの名前（GET /api/v1/audio-library の effects）か、自分が上げた音の url（POST /api/v1/assets/audio-uploads/confirm・/inline の data.url。素材管理で上げた効果音の url も可）。外部の URL・他人の素材は 400 validation_error（invalidAudio）。最大2秒鳴らし、行が短ければ行の長さまで。 null で鳴らさない
      - 'pa' | 'カメラのシャッター1' | 'キーンコーンカーンコーン' | 'きらーん1' | 'クイズ不正解1' | 'クイズ正解1' | 'ショック1' | 'ショック4' | 'ずっこける' | 'チーン1' | 'ナイフで突き刺す3' | 'パンチ' | 'パトカー' | 'ひらめく1' | 'ホラー1' | '和太鼓でドドン' | '心臓の鼓動1' | '決定ボタンを押す1' | '間抜け1' | '騒がしい高校の教室'
      - string: 自分が上げた音の url
    - `bgm` string, nullable: この行から流す BGM（任意）。次に bgm を書いた行まで引き継ぐ。組み込みの曲の名前（GET /api/v1/audio-library の bgm[].name。path でも可）・自分が上げた音の url（audio-uploads の data.url）・"none"（この行から止める）。曲の切り替えは 0.7 秒のクロスフェード、曲はループする。外部の URL・他人の素材は 400 validation_error（invalidAudio）。どの行にも書かなければ従来どおり（動画全体の BGM）。 null でこの行の指定を外す（前の行の BGM のまま。止めるなら "none"）。音声の作り直しは要らない。
    - `stage` StageEntry[], nullable: この行から舞台（画面）に立つキャラの並び（任意）。要素はキャラの id の文字列（テンプレートの枠の位置に立つ）か、立ち位置つきの {id, x?, y?, scale?, facing?}（StageEntry。文字列と混ぜてよい）。x はキャラの横の中心（画面の幅の %、0〜100。50 が真ん中）、y は枠の位置から下へずらす量（画面の高さの %、-50〜50）、scale は枠に対する大きさ（0.5〜2。tohoku-ahiru-talk と自作テンプレートは頭の高さを保つ、yukkuri-talk は下端を保つ）、facing は顔の向き（left / right。省くと x を書いたときは画面の中央の方を向く）。書かなかった項目は枠のまま。範囲の外・知らない項目は 400 validation_error。位置も stage と一緒に引き継ぎ、次に stage を書いた行で文字列で書いたキャラ・並びに無いのに台詞で登場したキャラは枠の位置に戻る。舞台に居るまま位置・大きさが変わると約0.3秒でなめらかに動く。位置を書いたキャラは4人の並び・素材の寄せに従わず書いた所に立ち続け、cameraMode dynamic はいま立っている所へ寄る。1人で真ん中に寄せるのは自動ではない（x:50 と書く）。台本で話すキャラだけ書ける（それ以外は 400 validation_error・invalidStage）。次に stage を書いた行まで引き継ぐ。並びから外したキャラはその行で退場し、加えたキャラは登場する（外側へ・外側から約0.3秒ですべる）。台詞のある行の話者は並びに無くても登場し、以後も残る（ただし offstage: true の行の話者は登場しない。voiceOnly のキャラは書けない＝400 voiceOnlyOnStage）。どの行にも書かなければ従来どおり（初めて話した行で登場し、最後まで残る）。描ける人数は動画全体の話者（声だけの話者は数えない）で数えて tohoku-ahiru-talk（とその複製）は4人まで、yukkuri-talk は2人（超えた話者は声と字幕だけ）。tohoku-ahiru-talk はその時点で舞台に居る人数で並ぶ（3人は2人と1人、4人そろうと左右に2人ずつ少し小さく。人数が変わると約0.3秒で並び直す）。story-talk では効かない。 null でこの行の指定を外す（前の行の舞台のまま）。
      - union: 行の stage の1人ぶん。キャラの id の文字列（テンプレートの枠の位置）か、立ち位置つきのオブジェクト。
        - string: キャラの id（台本で話すキャラ）。テンプレートの枠の位置に立つ
        - object
          - `id` string, required: キャラの id（台本で話すキャラ）
          - `x` number: キャラの横の中心（画面の幅の %）。50 が真ん中
          - `y` number: 枠の位置から下へずらす量（画面の高さの %）。マイナスで上へ
          - `scale` number: 枠に対する大きさ（1 が枠のまま）
          - `facing` 'left' | 'right': 顔の向き。省くと x を書いたときは画面の中央の方を向く（x が 45 未満なら右、55 を超えたら左）
    - `backgroundMotion` 'none' | 'zoomIn' | 'zoomOut' | 'panLeft' | 'panRight' | 'null', nullable: 背景のゆっくりした動き（任意）。none=止める（既定）/ zoomIn=寄る / zoomOut=引く / panLeft・panRight=カメラが左・右へ流れる。書いた行から、次に backgroundMotion を書いた行まで引き継ぐ（動画全体なら1行目に書く）。その背景が出ている間いっぱいをかけて最大8%動く（8秒より短い場面では小さく）。背景か動きを替えた行から頭から動く。画像の背景だけに効く（動画の背景は動かない）。cameraMode の寄りとは別で、重ねて使える。 null でこの行の指定を外す（前の行の動きのまま。止めるなら none）。
    - `transition` 'dissolve' | 'fadeBlack' | 'cut' | 'null', nullable: この行での場面転換の見せ方（任意。その行だけ）。dissolve=0.6秒で溶かす（既定）/ fadeBlack=行の頭の前後0.4秒ずつの暗転（画面全体。背景を変えない行でも暗転する）/ cut=一瞬で切り替え。dissolve・cut は、その行で backgroundImageUrl か backgroundMotion が変わるときだけ効く。 null で既定（dissolve）。
    - `eyecatch` union: この行の前に挟む全画面の章タイトル（任意）。文字列なら見出しだけ、{title, subtitle} なら小見出しつき（見出し30文字・小見出し40文字まで）。背景を暗くぼかしてキャラを消し、見出しを1.8秒出す（横長・縦型とも）。その行の音声の前に1.8秒の無音の間を足してそこに出すので台詞とは重ならない——そのぶん動画が1.8秒ずつ長くなり、本番 MP4 のクレジット（動画1分につき1）と受け付けの見積もりにも入る。同じ行で背景・backgroundMotion・stage を変えると、アイキャッチの裏で入れ替わる。 null で外す（無音の間も無くなる）。音声は作り直さなくてよい。
      - string
      - object
        - `title` string, required
        - `subtitle` string
    - `action` union: この行の頭でキャラが1回する動き（任意。その行だけ・引き継がない）。立ち絵の全体を動かすので組み込み・自作（PNG・PSD）・ゆっくりのどれにも効き、口パク・表情・ポーズは続く。文字列はその行の話者、{type, target} は target のキャラ（台本で話して画面に出るキャラだけ。ほかは 400 validation_error・invalidAction）、配列で複数（4つまで。同じキャラは最初の1つ）。jump=跳ぶ（約0.8秒）/ hop=ぴょんぴょん2回（約0.6秒。同じ行の stage で立ち位置が変わるなら跳ねながら移る。1回約0.3秒で2〜4回）/ shake=震える（約0.6秒）/ bow=顔の向きへお辞儀（約1秒）/ spin=振り向く（約0.5秒。同じ行で facing が変わればその向きへ、変わらなければ一回り）/ fall=ずっこける（行の長さに合わせて1.3〜3秒で起き上がる）/ bounce=はしゃぐ（約0.75秒）。動き出すのは行の音声の頭（アイキャッチの後・その行で登場するキャラは入りきってから）。目安: 盛り上がり・驚き・オチ・あいさつに。毎行には付けない。story-talk では効かない。 null で外す。
      - union: 行の action の1つぶん。動きの名前の文字列（その行の話者が動く）か {type, target?}。
        - 'jump' | 'hop' | 'shake' | 'bow' | 'spin' | 'fall' | 'bounce'
        - object
          - `type` 'jump' | 'hop' | 'shake' | 'bow' | 'spin' | 'fall' | 'bounce', required: 動きの名前
          - `target` string: 動くキャラの id（台本で話すキャラ。省くとその行の話者）
      - ActionEntry[]
        - union: 行の action の1つぶん。動きの名前の文字列（その行の話者が動く）か {type, target?}。
          - 'jump' | 'hop' | 'shake' | 'bow' | 'spin' | 'fall' | 'bounce'
          - object
            - `type` 'jump' | 'hop' | 'shake' | 'bow' | 'spin' | 'fall' | 'bounce', required: 動きの名前
            - `target` string: 動くキャラの id（台本で話すキャラ。省くとその行の話者）
    - `voice` LineVoice: 行の voice（声の速さ・高さ。その行だけ）。自作キャラの既定の voice も同じ形。
      - `speed` number: 話す速さ（1 が標準）
      - `pitch` number: 声の高さ（0 が標準）
    - `offstage` boolean, nullable: true でこの行の話者は声だけ（任意。舞台の外から話す・電話の声など）。その台詞では舞台に出てこない（台詞による自動の登場をしない）。既に舞台に居るキャラは残る（口も動く）——姿を消すなら同じ行の stage から外す。offstage の行でしか話さず、どの行の stage にも無いキャラは一度も画面に出ず、枠も使わない。この行の cameraMode dynamic は寄らない。この行の話者を action で動かす（target を省いたものを含む）・camera の target にする（"speaker" を含む）のは 400 validation_error（invalidAction / invalidCameraTarget）。camera の target を省くと寄る先は画面の真ん中。字幕・音声は普段どおり。その行だけ（引き継がない）。story-talk ではその行の話者の絵を出さない。 false・null で外す（台詞で登場する従来どおり）。音声は作り直さなくてよい。

## Response `200`

更新できた

- object
  - `success` boolean
  - `projectId` string
  - `updated` integer[]: 実際に書き換えた行番号
  - `lineCount` integer
  - `audioInvalidated` integer[]: 音声が無効になった行番号。レンダー前に generate_audio が要る。
  - `nextStep` string: audioInvalidated が空でないときだけ付く

## Other responses

- `400`: リクエスト不正（code: validation_error / duplicate_index / unknown_speaker）
- `401`: 未認証（code: unauthenticated）
- `403`: 権限不足（projects:write / code: insufficient_scope）
- `404`: プロジェクトが無い（code: not_found）・その行番号が無い（code: line_not_found）

## 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 `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`
  - …28 more

[Operation history](https://skmtc.dev/yukkurigen/apis/yukkurigen-ai-operated-api/changes/api/v1/projects/:projectId/lines/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)