agent

台本 → MP4 を1コールで生成

Changed on
post/api/v1/agent/generate

Request

  • Base URL: https://app.yukkurigen.com
  • URL: https://app.yukkurigen.com/api/v1/agent/generate
  • Auth: one of:
    • HTTP bearer
    • HTTP bearer

Headers

Prefer'respond-async'

respond-async を付けて output:"mp4" を呼ぶと、門（認証・スコープ・プラン・レート上限・callbackUrl・クレジット）をその場で通してから、数秒で 202 とジョブが返る（RFC 7240。サーバの設定によっては付けてもジョブにならず、同期で処理して 200 を返す）。GET /api/v1/jobs/{jobId} で succeeded を待ち、result.renderId を進捗のポーリングに渡す。失敗したジョブのクレジットは返金される。例外は、レンダーを起動したあとにジョブだけが失敗した場合（まれ）で、レンダーは課金されたまま動いていて返金されず、Idempotency-Key も空かない（同じ鍵で投げ直すと、Prefer を付けていても起動済みのレンダーが 200 で返る）。renderId に agent-{jobId} を渡して進捗を見れば結果が分かる（not_found なら起動しておらず、返金される）。output:"draft" は常に同期。省略すると同期処理（既存互換。サーバの設定によっては、同じ受け付けのあと一定時間だけ完了を待ち、終わらなければ 202 を返す）。

Request body

output'mp4' | 'draft'

何を返すか。mp4=本番レンダー（動画1分につき1クレジット・端数切り上げ・有料プランかクレジットパックで買ったクレジット・サーバで音声を合成してから焼く。受け付けで台本の文字数（各行の text と reading の長いほう）から多めに見積もって押さえ、実際の長さで精算する。差額を引けなければ焼かずにジョブが insufficient_credits で失敗し、押さえた分は全額返る）／draft=プロジェクトと台本を作るところで止める（消費なし・数秒で返る）。mp4 は合成とレンダー開始を待つため、10行の台本で45秒を超えることがある——idempotencyKey を付けるか、draft で作ってから generate_audio → render_mp4 と刻む。mp4 は renderId を返すので進捗をポーリングする（callbackUrl を渡せば通知も届く）。

titlestring

動画のタイトル（テーマ）。横長の動画では画面の左上に出し続ける（titleTelop:false で消せる）。

titleTelopboolean

タイトルを出すか。横長は左上（章の見出しがあると最初の章より前の行だけ）、縦型は画面の上にずっと。false で両方とも消す。省略時は title を渡したときだけ出す。

templateIdstring

テンプレートid（任意）。list_templates が返す id をそのまま渡す——system（5種）でも mine（自作）でもよい。存在しない/他人のものなら 400 template_not_found（課金なし）。省略すると台本の話者から選ぶ。

channelIdstring

チャンネルid（省略可。テンプレートの既定を引く）

voicePlaybackRatenumber

動画全体の読み上げの再生速度（0.5〜2.0。既定 1.1）。焼くときと共有リンクで音声の再生に掛かる（音声の作り直しは要らない）。プロジェクトの voice_playback_rate に残り、共有リンク・あとの render も同じ速さになる。行ごとの速さ・高さは script[].voice（掛け合わせ）。

voiceOnlystring[]

動画全体で姿を出さず、声だけで話すキャラの id の並び（任意。8人まで。ナレーター・電話の声など）。台本で話すキャラだけ（それ以外は 400 validation_error・invalidVoiceOnly）。そのキャラは一度も画面に出ない: 台詞の行でも舞台に立たず、テンプレートの枠も使わない（空いた枠はほかの話者が使う）、その行の cameraMode dynamic でも寄らない、4人の並び・描ける人数にも数えない。声と字幕は普段どおり。stage に書く・action で動かす・camera の target にするのは 400（voiceOnlyOnStage / invalidAction / invalidCameraTarget）。プロジェクトの voice_only に残り、あとから PATCH /projects/{id}/settings の voiceOnly で変えられる。話者の検査（cast_mismatch）は声だけのキャラにも掛かる。

backgroundImageUrlstring

動画全体の背景画像/動画のURL（https のみ、内部アドレス不可）。省略すると既定の背景（室内のイラスト）になる。

callbackUrlstring uri

完了通知の宛先（mp4 のときだけ意味を持つ）。https のみ・内部アドレス不可。

platform'youtube' | 'tiktok' | 'shorts'

出力プラットフォーム。shorts / tiktok は縦型になる。

idempotencyKeystring

冪等キー（任意）。Idempotency-Key ヘッダと同じ働きで、ヘッダが無いときに使われる。同じ鍵で投げ直せば最初の結果が返り、課金は起きない（24時間）。処理中なら 409 code:"in_flight"。

Response

生成成功（同期の経路、同じ鍵の完了済み結果の再送、または Prefer なしの呼び出しをサーバが待つ設定で、待つ間にジョブが終わったとき）。レンダーを起動したあとにジョブだけが失敗した場合（まれ）も、同じ Idempotency-Key の再送（Prefer を付けていても）とサーバの待ちには、起動済みのレンダー（renderId: agent-{jobId}）がこの 200 で返る。そのレンダーは課金されたまま動いていて返金されず、2本目は作られない。

projectIdstring required

作成したプロジェクトのID

renderIdstring required

レンダーのID。進捗の取得に使う

statusstring required
estimatedTimenumber

完了までの目安（秒）

callbackUrlstring

登録した通知先（渡したときだけ）

callbackSecretstring

通知の署名検証に使う（利用者ごとに固定）

callbackSignatureHeaderstring

Example response

{
  "status": "rendering",
  "callbackSignatureHeader": "X-Yukkurigen-Signature"
}

Changes

  • ba5f36b016daRevision changes
    • warning

      added the new already_subscribed enum value to the response property for the response status

    • warning

      added the new already_subscribed enum value to the response property for the response status

    • warning

      added the new already_subscribed enum value to the response property for the response status

    • warning

      added the new already_subscribed enum value to the response property for the response status

    • warning

      added the new already_subscribed enum value to the response property for the response status

    • warning

      added the new already_subscribed enum value to the response property for the response status

    • warning

      added the new already_subscribed enum value to the response property for the response status

    • warning

      added the new already_subscribed enum value to the response property for the response status

    • warning

      added the new render_not_paid enum value to the response property for the response status

    • warning

      added the new render_not_paid enum value to the response property for the response status

    • warning

      added the new render_not_paid enum value to the response property for the response status

    • warning

      added the new render_not_paid enum value to the response property for the response status

    • warning

      added the new render_not_paid enum value to the response property for the response status

    • warning

      added the new render_not_paid enum value to the response property for the response status

    • warning

      added the new render_not_paid enum value to the response property for the response status

    • warning

      added the new render_not_paid enum value to the response property for the response status

    • warning

      added the new render_not_ready enum value to the response property for the response status

    • warning

      added the new render_not_ready enum value to the response property for the response status

    • warning

      added the new render_not_ready enum value to the response property for the response status

    • warning

      added the new render_not_ready enum value to the response property for the response status

    • warning

      added the new render_not_ready enum value to the response property for the response status

    • warning

      added the new render_not_ready enum value to the response property for the response status

    • warning

      added the new render_not_ready enum value to the response property for the response status

    • warning

      added the new render_not_ready enum value to the response property for the response status

    • warning

      added the new tts_quota_exceeded enum value to the response property for the response status

    • warning

      added the new tts_quota_exceeded enum value to the response property for the response status

    • warning

      added the new tts_quota_exceeded enum value to the response property for the response status

    • warning

      added the new tts_quota_exceeded enum value to the response property for the response status

    • warning

      added the new tts_quota_exceeded enum value to the response property for the response status

    • warning

      added the new tts_quota_exceeded enum value to the response property for the response status

    • warning

      added the new tts_quota_exceeded enum value to the response property for the response status

    • warning

      added the new tts_quota_exceeded enum value to the response property for the response status

    • warning

      added the new youtube_not_connected enum value to the response property for the response status

    • warning

      added the new youtube_not_connected enum value to the response property for the response status

    • warning

      added the new youtube_not_connected enum value to the response property for the response status

    • warning

      added the new youtube_not_connected enum value to the response property for the response status

    • warning

      added the new youtube_not_connected enum value to the response property for the response status

    • warning

      added the new youtube_not_connected enum value to the response property for the response status

    • warning

      added the new youtube_not_connected enum value to the response property for the response status

    • warning

      added the new youtube_not_connected enum value to the response property for the response status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status