確認日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 はすべて同じサービスを読むため、同じワークスペースルールが適用されます。結果は各リクエスト時点の 現在の状態を反映します。別々のリクエストが、その間の更新を観察することがあります。