审校于 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_…)仅显示一次;系统只存储哈希值和短前缀。以 bearer token 形式发送它:
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:不会删除任何内容,撤销界面会先显示受影响的待处理任务数。
基本规则
- 每次变更操作都需要
Idempotency-Key请求头。相同密钥 + 相同请求体 → 相同的已记录结果(相同的交付 ID)。相同密钥 + 不同请求体 →409 idempotency_conflict。 - 编辑和排期需要
expectedVersion;过期的版本会返回409 revision_conflict,并在error.details.currentVersion中包含当前版本。 - 发布/排期返回的
202表示已被接受待分发,绝不表示"已发布"。通过GET /posts/{id}、客户 webhook 或有界轮询跟踪结果。 - 速率限制是每个工作区的技术限速(按套餐为 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"
对于图片/视频目标,先上传并完成媒体处理,然后在 mediaIds 中使用返回的资产 ID 以及一个合格的目标格式。从已接受的响应中记录各个交付 ID;使用 webhook 或带退避的有界状态轮询。单次立即状态读取可能仍处于 pending 状态。
排期而非发布
在草稿上使用此操作,替代上面的发布步骤。任何编辑之后都要重新获取其当前版本。这里计算一个未来的时刻,而不是使用会过期的示例日期。
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 的游标指向仍待扫描的更早记录。优先使用 webhook(参见 webhooks)或带退避的有界轮询,而不是紧密的状态循环。
限制与部分成功
目标能力(来自 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 指向已认证编辑器中保存的草稿。校验可以在其结构化问题旁返回同样的交接。相关人员在那里审查确切的视频/文案并做出明确选择;产品密钥和 MCP 无法代其确认。在人员确认后,通过正常的共享发布服务重试。编辑内容或更改目标身份需要重新审查。交接 URL 不包含产品密钥、令牌或签名的媒体 URL,也不会向缺乏工作区成员资格的人员授予任何访问权限。其工作区 UUID 标识密钥所属的工作区;选择了不同工作区的浏览器必须先通过当前成员资格检查并明确切换后,才能审查此草稿。
完整、最新的契约参见 OpenAPI 规范。UI、REST 和 MCP 都读取相同的服务,因此它们应用相同的工作区规则。结果反映每个请求时的当前状态;单独的请求可能观察到中间发生的更新。