動画や画像に透かしを追加、ロゴ・テキストオーバーレイに対応するAPI
1回のPOSTで、任意の動画や画像にロゴ画像またはテキストを重ねられます。位置・不透明度・スケールをリクエストでそのまま指定でき、Fotovidがホストするファイルがすぐ配信できる状態で返ってきます。
curl -X POST https://api.fotovid.co/v1/video/watermark \
-H "Authorization: Bearer p6_YOUR_KEY_ID:YOUR_SECRET" \
-H "Content-Type: application/json" \
-d '{
"source_url": "https://cdn.yoursite.com/clip.mp4",
"params": {
"type": "image",
"watermark_image_url": "https://cdn.yoursite.com/logo.png",
"position": "bottom-right",
"opacity": 0.7,
"scale": 0.2
}
}'serverless上での透かし処理がつらい理由
透かし処理は単純に見えますが、serverless関数の中で実行しようとした瞬間に話が変わります。ffmpegのオーバーレイフィルターにはバイナリ本体一式とロゴを書き込み可能なディスクに配置する必要があり、そのうえファイル全体をデコード・再エンコードします。これは短いクリップを超える長さになるだけで、LambdaやVercelの実行時間制限やメモリ上限を簡単に超えてしまいます。ロゴを隅に1つ焼き込むためだけに、レイヤーのバンドル管理や一時ストレージ、コールドスタートまで面倒を見る羽目になります。
- ffmpegのバイナリとライブラリでデプロイサイズが膨らみ、一般的なserverlessのサイズ制限を大きく超える
- 動画全体の再エンコードで関数のタイムアウトとメモリ上限を超過する
- 画像を重ねるには、一時ディスク上でのファイル取得・配置・後始末が必要になる
- 解像度をまたいで位置・不透明度・スケールをピクセル単位で合わせ込むのは、フィルターグラフの細かい調整作業になる
リクエストパラメータ
POST /v1/video/watermark & /v1/image/watermark
| Field | Type | Default | Description |
|---|---|---|---|
| source_url* | string (URL) | — | 元となる動画または画像のHTTPS URL |
| params.type | "image" | "text" | "combo" | "text" | 透かしの種類 |
| params.watermark_image_url | string (URL) | — | ロゴ画像のURL（image/comboの場合は必須） |
| params.text | string | — | 重ねるテキスト（text/comboの場合は必須） |
| params.position | string | "bottom-right" | top-left · top-right · bottom-left · bottom-right · center |
| params.opacity | number | 1 | 0〜1 |
| params.scale | number | 0.15 | 元の動画・画像に対する透かしの幅の比率（0〜1） |
最初の呼び出しを3ステップで
- 1無料のAPIキーを取得する
サインアップしてキーを作成します。すべてのリクエストは Authorization: Bearer p6_<key_id>:<secret> ヘッダーで認証します。開始にカードは不要です。利用はcredits制で動きます（$1 = 100 credits、透かし処理は1 credit）。
- 2元データと透かしのパラメータをPOSTする
POST /v1/video/watermark または POST /v1/image/watermark を、標準のエンベロープ形式で呼び出します。入力先を指す source_url（https URL）と params オブジェクトを渡します。type に image、text、combo のいずれかを設定し、watermark_image_url や text を渡すとともに、position（top-left、top-right、bottom-left、bottom-right、center のいずれか）、opacity（0〜1）、scale（0〜1、デフォルト0.15）、padding を指定します。Fotovidが入力を取得して透かしを重ね、同期的に結果を返します。
- 3返却された結果URLを保存する
レスポンスは id、type、そして透かし処理済みファイルのFotovidホストのurlを含むフラットなJSONです（動画レスポンスにはdurationも含まれます）。ダウンロードして自分側にも保存してください。このホストURLは期限切れになるため、恒久的なストレージではなく受け渡し用として扱ってください。
