AiVideoEditor
無料で始める
メニュー

確認日2026-11-11 · API版2026-11-09 · Markdownを読む

AiVideoEditor API クイックスタート

ベース URL: https://<your-app-host>/api/v1 (ローカル開発: http://localhost:3006/api/v1)。

認証

ワークスペースのナビゲーションにある Developers (/app/developers) でプロダクトキーを作成します。平文の キー (pk_v1_…) は 一度だけ 表示されます。保存されるのはハッシュと短いプレフィックスのみです。 キーはベアラートークンとして送信します:

curl -H "Authorization: Bearer $PUBLISHER_KEY" https://app.example.com/api/v1/usage

キーは明示的なスコープ (accounts:read、media:write、posts:read、 posts:write、posts:publish、usage:read、webhooks:manage) と、オプションの アカウント許可リストを持ちます。下書き専用 のキーは posts:publish を含まないため、 公開・予約・キャンセル・再試行はできません。キーが他のキーを作成したり請求を変更したりすることは 決してできません。キーを失効させると、未送信のジョブは requires_action として 一時停止 されます。 何も削除されず、失効 UI では影響を受ける保留中ジョブの件数を先に表示します。

基本ルール

  • すべてのミューテーション には Idempotency-Key ヘッダーが必要です。同じキー + 同じボディ → 同じ記録結果 (同じ配信 ID)。同じキー + 異なるボディ → 409 idempotency_conflict。
  • 編集と予約には expectedVersion が必要です。古いバージョンを指定すると、現在のバージョンを error.details.currentVersion に入れた 409 revision_conflict が返されます。
  • 公開/予約からの 202 は 配送の受付 を意味するものであり、決して「公開済み」ではありません。 結果は GET /posts/{id}、カスタマーウェブフック、または上限付きポーリングで追跡します。
  • レート制限は ワークスペースごとの技術的な速度制限 です (プランにより 60/120/240 リクエスト/分。429 + Retry-After)。リクエスト数や投稿数の割り当ては存在せず、 投稿はすべての有料プランで無制限です。
  • エラーは正規化されたエンベロープを使用します: { error: { code, message, fieldErrors?, destinationErrors?, retryable?, retryAfterSeconds?, requestId } }。

エンドツーエンド: 下書き → 検証 → 公開 → 観察

この例では、Bash、curl、jq、Node 22+、有効なワークスペース、 接続済みの Facebook ページまたは LinkedIn の宛先、および accounts:read、posts:read、posts:write、posts:publish を持つキーが必要です。ACCOUNT_ID には /accounts から許可された宛先を設定し、/capabilities でテキストフォーマットの対応を確認してください。公開コマンドを実行すると、実際のコンテンツが投稿されます。

set -euo pipefail
BASE="${PUBLISHER_API_URL:?Set the AiVideoEditor origin}/api/v1"
AUTH="Authorization: Bearer ${PUBLISHER_KEY:?Set the product key}"
JSON="Content-Type: application/json"
new_key() { node -e 'console.log(require("node:crypto").randomUUID())'; }

curl --fail-with-body -sS -H "$AUTH" "$BASE/accounts"
curl --fail-with-body -sS -H "$AUTH" "$BASE/capabilities"
: "${ACCOUNT_ID:?Choose a permitted text destination from the responses above}"

# Save this key and body; reuse both if the connection fails ambiguously.
CREATE_KEY=$(new_key)
DRAFT_BODY=$(jq -n --arg account "$ACCOUNT_ID" '{caption:"A new update from our team.",mediaIds:[],brandFolderId:null,destinations:[{accountId:$account,format:"text"}]}')
DRAFT=$(curl --fail-with-body -sS -X POST -H "$AUTH" \
  -H "Idempotency-Key: $CREATE_KEY" -H "$JSON" \
  "$BASE/posts" -d "$DRAFT_BODY")
POST_ID=$(jq -er '.post.postId' <<<"$DRAFT")
VERSION=$(jq -er '.post.version' <<<"$DRAFT")

VALIDATION=$(curl --fail-with-body -sS -X POST -H "$AUTH" "$BASE/posts/$POST_ID/validate")
printf '%s\n' "$VALIDATION"
jq -e '.validation.valid == true' <<<"$VALIDATION" >/dev/null

# 202 means accepted. Keep this key for an identical retry after a timeout.
PUBLISH_KEY=$(new_key)
ACCEPTED=$(curl --fail-with-body -sS -X POST -H "$AUTH" \
  -H "Idempotency-Key: $PUBLISH_KEY" "$BASE/posts/$POST_ID/publish")
printf '%s\n' "$ACCEPTED"
curl --fail-with-body -sS -H "$AUTH" "$BASE/posts/$POST_ID"

画像/動画の宛先では、まず メディアをアップロードして確定 し、返されたアセット ID を mediaIds に、適格な宛先フォーマットを使用してください。受け付けたレスポンスから個々の配信 ID を観察し、 ウェブフックまたはバックオフ付きの上限付きステータスポーリングを使用します。直後の 1 回のステータス読み取りでは、 まだ処理中のままの場合があります。

公開の代わりに予約する

上の公開ステップの 代わりに、下書きに対してこれを使用します。編集を行った後は、現在の バージョンを再度取得してください。これは期限切れになるサンプルの日付を使用するのではなく、 未来の時刻を計算します。

SCHEDULED_AT=$(node -e 'console.log(new Date(Date.now()+86400000).toISOString())')
SCHEDULE_BODY=$(jq -n --arg at "$SCHEDULED_AT" --argjson version "$VERSION" \
  '{scheduledAt:$at,timezone:"America/Indiana/Indianapolis",expectedVersion:$version}')
SCHEDULE_KEY=$(new_key)
curl --fail-with-body -sS -X POST -H "$AUTH" -H "Idempotency-Key: $SCHEDULE_KEY" \
  -H "$JSON" "$BASE/posts/$POST_ID/schedule" -d "$SCHEDULE_BODY"

時刻は未来で、かつ 90 日のホライズン内 でなければなりません。UTC の時刻インスタントと 表示用タイムゾーンは別々に保存されます。API キーの有効期限がその時刻以前に到来する場合、 受け付けたレスポンスにはコード key_expires_before_schedule を持つ warnings エントリが含まれます。 配信は予約されたままですが、公開できるようになる前に、有効な主体のもとで 確認と再提出が必要です。同じ警告はリクエストを再生した場合にも保持されます。安全に未処理の間にキャンセルします:

curl -s -X POST -H "$AUTH" -H "Idempotency-Key: $(new_key)" $BASE/deliveries/$DELIVERY_ID/cancel
# Already submitted? → 409 too_late_to_cancel with the real state.

既知の失敗した宛先 のみ 再試行します (不明/成功済みは拒否されます):

curl -s -X POST -H "$AUTH" -H "Idempotency-Key: $(new_key)" $BASE/deliveries/$DELIVERY_ID/retry

メディア (ダイレクトアップロード)

メディアのバイト列がこの API を経由することは決してありません。

# 1. Reserve bytes → direct instructions (presigned PUT, or multipart for large files)
curl -s -X POST -H "$AUTH" -H "Idempotency-Key: $(new_key)" -H "$JSON" $BASE/media/upload-intents -d '{
  "filename": "poster.jpg", "declaredMime": "image/jpeg", "declaredBytes": 1048576 }'

# 2. Upload bytes DIRECTLY to the returned URL with the documented method.

# 3. Finalize: the server verifies size/signature on the immutable final copy.
#    Send ONLY the session identity (plus part receipts for multipart uploads)
#: bytes, MIME and checksum are observed server-side, never declared here.
curl -s -X POST -H "$AUTH" -H "Idempotency-Key: $(new_key)" -H "$JSON" $BASE/media/$ASSET_ID/finalize -d '{
  "sessionId": "…" }'

# multipart: include the ETag receipt of every uploaded part.
# Files at or above 50 MiB use multipart; use the returned part size and URLs.
# Upload every part and retain its ETag. Small files finalize with sessionId only.
# These are alternative finalization shapes, not two consecutive operations.
curl -s -X POST -H "$AUTH" -H "Idempotency-Key: $(new_key)" -H "$JSON" $BASE/media/$ASSET_ID/finalize -d '{
  "sessionId": "…",
  "multipart": { "parts": [ { "partNumber": 1, "etag": "…" } ] } }'

# 4. Status/expiry only: there is no permanent public media URL
curl -s -H "$AUTH" $BASE/media/$ASSET_ID

ファイルは一時的なものです: 予約済みの投稿は公開の間メディアを保持し、 動的な deleteAfter (または null) が常に表示されます。元のファイルはご自身で保管してください。

使用状況

GET /usage はプラン、接続済み/予約済みのアカウントスロット、メンバー、ストレージ、 90 日のホライズン、レート情報を報告します。アクティビティの数値は運用指標にすぎません: 製品内のどこにも残り投稿数カウンターは存在しません。

ページネーション

リスト系エンドポイントは不透明なカーソルを使用します: ?limit=25&cursor=<nextCursor>。タイムスタンプは UTC の ISO-8601 です。nextCursor が null になるまで続行してください。フィルターされた投稿ページが 空であっても、非 null のカーソルがまだ走査すべき古いレコードを指していることがあります。 細かいステータスのループよりも、ウェブフック (ウェブフック を参照) またはバックオフ付きの上限付きポーリングを推奨します。

制限と部分的成功

宛先の機能 (capability、GET /capabilities から取得) は、アプリ、プロバイダー、 ネットワーク、アカウントの中で最も厳しい実効制限を反映します。制限がリクエストを ブロックした場合、エラーエンベロープは対処につながる内容を持ちます:

{
  "error": {
    "code": "storage_limit",
    "message": "Active temporary media exceeds this plan's storage allowance.",
    "retryable": false,
    "requestId": "…"
  }
}

account_limit、seat_limit、storage_limit、subscription_inactive と trial_expired は 402 レスポンスです。何も削除されず、下書き/待機中の作業は アップグレード後に備えて保持されます。

公開/予約は、独立した宛先ジョブのバッチです。部分的成功は正常であり、宛先ごとに報告されます。 決してアトミックな約束として提示してはなりません:

{
  "post": {
    "postId": "…",
    "version": 4,
    "status": "partially_published",
    "deliveries": [
      { "id": "…", "accountId": "…", "network": "instagram", "state": "published",
        "nativePostUrl": "https://instagram.com/p/…", "unresolvedExternalOutcome": false },
      { "id": "…", "accountId": "…", "network": "linkedin", "state": "reconnect_required",
        "nativePostUrl": null, "lastErrorCode": "reconnect_required" }
    ]
  },
  "requestId": "…"
}

失敗した宛先のみ再試行し (POST /deliveries/{id}/retry)、成功した 宛先は決して再送しません。同意/再接続の要件は、安全な指示とともに requires_action を返します。秘密情報は決して含まれません。

完全なリファレンス

TikTok の場合、GET /accounts/{id}/tiktok/settings は接続済みクリエイターの 現在のプライバシー選択、インタラクション権限、長さ制限、公開 モードの利用可否を返します。accounts:read が必要で、キーの許可リストに従います。 下書きの保存やこれらの設定の読み取りは、同意の提供にはなりません。

現在の人間による確認を欠いた公開/予約は、HTTP 409 consent_required を返し、error.requiresAction.url が認証済みコンポーザー内の保存済み下書きを 指します。検証も、構造化された問題とともに同じハンドオフを返すことがあります。その場で人が正確な動画/SNS用キャプションを確認し、 選択を明示的に行います。プロダクトキーや MCP が人の代わりに確認することはできません。 人が確認した後は、通常どおり共有公開サービスを通じて再試行します。 コンテンツの編集や宛先の同一性の変更には、新たなレビューが必要です。 ハンドオフ URL にはプロダクトキー、トークン、署名付きメディア URL は含まれず、ワークスペースの メンバーシップを持たない人にアクセスを与えることもありません。そのワークスペース UUID は キーのワークスペースを識別します。別のワークスペースを選択しているブラウザーは、この下書きを確認する前に、現在のメンバーシップ確認を経て明示的に 切り替える必要があります。

完全で最新のコントラクトについては OpenAPI 仕様 を参照してください。UI、REST と MCP はすべて同じサービスを読むため、同じワークスペースルールが適用されます。結果は各リクエスト時点の 現在の状態を反映します。別々のリクエストが、その間の更新を観察することがあります。