---
title: "MP4 レンダーを開始（Remotion Lambda・非同期・5cr）"
method: POST
path: "/api/v1/projects/{projectId}/render"
tags: ["projects"]
---

# MP4 レンダーを開始（Remotion Lambda・非同期・5cr）

`POST /api/v1/projects/{projectId}/render`

## Request

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

## Path parameters

- `projectId` string, required

## Request body

- object
  - `outputFormat` 'landscape' | 'portrait': 使わなくてよい。向きは platform で決まる（platform を省き、プロジェクトにも向きが無いときだけ portrait=縦型として扱う）
  - `platform` 'youtube' | 'tiktok' | 'shorts': 向きと用途。shorts / tiktok は縦型。省略するとプロジェクトを作ったときの platform（GET /projects/{id} の project.platform）
  - `codec` 'h264' | 'vp8' | 'vp9'
  - `waitForCompletion` boolean: 非推奨・無視される（2026-09-15）。true でも待たずに、常に status:"rendering" と renderId を返すので、進捗（GET .../render/{renderId}/progress、MCP なら get_render）で完了を追う。送っても 400 にはならない。
  - `fontSize` number
  - `titleFontSize` number
  - `voicePlaybackRate` number: 動画全体の読み上げの再生速度（0.5〜2.0。既定 1.1）。焼くときと共有リンクで音声の再生に掛かる（音声の作り直しは要らない）。プロジェクトの voice_playback_rate に残り、共有リンク・あとの render も同じ速さになる。行ごとの速さ・高さは script[].voice（掛け合わせ）。省略するとプロジェクトの値（無ければ 1.1）。渡すとプロジェクトにも残る。焼かずに変えるなら PATCH /api/v1/projects/{projectId}/settings。
  - `bgmVolume` number
  - `showOutroCard` boolean
  - `materialImageFilter` string[]: 素材画像にかけるフィルタ。未指定ならプロジェクトの設定を使う
  - `title` string: 動画内に出すタイトル（プロジェクト名と別にしたいとき）
  - `preview` object: 廃止（2026-09-27）。送ると 410 preview_removed（課金なし）。焼く前の確認は POST /api/v1/projects/{projectId}/preview-link の共有リンク（0クレジット・全編・音つき）。
    - `fromLine` integer, required: 開始行
    - `toLine` integer: 終了行（省略時は fromLine の1行）
  - `callbackUrl` string, uri: 完了/失敗したらここへ POST する。https のみ・内部アドレス不可（弾いた場合は課金せず 400）。本文は {event, projectId, renderId, status, downloadUrl?, occurredAt}。X-Yukkurigen-Signature: t=<unix秒>,v1=HMAC-SHA256(callbackSecret, "<t>.<本文>") を検証すること。callbackSecret はこの応答で返る（利用者ごとに固定）。t が現在時刻から5分以上離れていたら捨てること。
  - `idempotencyKey` string: 冪等キー（任意）。`Idempotency-Key` ヘッダと同じ働きで、ヘッダが無いときに使われる。同じ鍵で投げ直せば最初の結果が返り、課金は起きない（24時間）。処理中なら 409 code:"in_flight"。

## Response `200`

開始。常に status:"rendering" と renderId を返す——waitForCompletion を付けても待たずに status: rendering で返る（非推奨・無視）。200 は完了ではないので、進捗（GET .../render/{renderId}/progress）で完了を追うこと。

- object
  - `renderId` string
  - `status` 'rendering'
  - `callbackUrl` string: 登録された通知先（指定した場合のみ）。
  - `callbackSecret` string: 署名の検証に使う鍵（callbackUrl を指定した場合のみ返る。利用者ごとに固定）。
  - `callbackSignatureHeader` string: 署名が載るヘッダ名。

## Other responses

- `400`: リクエスト不正（code: validation_error）
- `401`: 未認証（code: unauthenticated）
- `402`: 権限またはクレジット不足（purchaseUrl 同梱）。code: insufficient_credits は残高が足りない（shortfall と、不足を満たす最小のパックを purchase に同梱）。code: plan_required は無料プランで、有料プラン・買い切りライセンス・購入したクレジット（パック）の残りのどれも無い（purchase=standard と、少額の代わりとして alternative=いちばん小さいクレジットパックを同梱。パックは無料プランでも買える）。この鍵は解放されるので、購入・アップグレード後は同じ鍵でそのまま再試行してよい。
- `403`: 権限不足（render:mp4 / code: insufficient_scope）
- `404`: プロジェクトが無い（code: not_found）
- `409`: 同じ Idempotency-Key の処理が進行中（code: in_flight）。少し待って同じ鍵で再試行する。
- `429`: レート上限（code: rate_limited、retryAfter 同梱）
- `500`: レンダー開始に失敗（code: render_start_failed）。予約分を返金済み、または返金待ちとして記録済みで後追いの掃除処理が戻すため、応答時点の残高にはまだ反映されていないことがある（返金と記録の両方の書き込みが落ちた場合はサーバログにのみ残る）。いずれの場合も残高は GET /api/v1/credits で確認できる。
- `503`: 冪等キーの判定ができなかった場合は鍵が取られておらず課金も起きていないので、同じ鍵でそのまま再試行する。クレジット確保に失敗した場合は課金の成否が確定しておらず鍵は保持されるので、GET /api/v1/credits で残高を確認し、しばらく置いてから同じ鍵で再試行する（鍵は65分で解ける）。

## Changes

- **2026-10-20** `ba5f36b016da`: 45 warning, 27 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 `402`
  - added the new `already_subscribed` enum value to the `code` response property for the response status `403`
  - …68 more

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