AiVideoEditor
Bắt đầu miễn phí
Trình đơn

Đã xem lại 2026-11-11 · Phiên bản API 2026-11-09 · Đọc Markdown

Hướng dẫn nhanh API của AiVideoEditor

URL cơ sở: https://<your-app-host>/api/v1 (môi trường dev cục bộ: http://localhost:3006/api/v1).

Xác thực

Tạo khóa sản phẩm trong Developers trên thanh điều hướng không gian làm việc (/app/developers). Khóa dạng văn bản thuần (pk_v1_…) chỉ được hiển thị đúng một lần; chỉ có một băm và một tiền tố ngắn được lưu. Gửi nó dưới dạng bearer token:

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

Khóa mang các phạm vi rõ ràng (accounts:read, media:write, posts:read, posts:write, posts:publish, usage:read, webhooks:manage) và một danh sách cho phép tài khoản tùy chọn. Khóa chỉ bản nháp bỏ qua posts:publish và vì vậy không thể đăng, lên lịch, hủy hoặc thử lại. Khóa không bao giờ có thể tạo khóa khác hoặc thay đổi thanh toán. Việc thu hồi một khóa sẽ tạm dừng các công việc chưa gửi đi của nó với trạng thái requires_action: không có gì bị xóa, và giao diện thu hồi hiển thị số công việc đang chờ bị ảnh hưởng trước tiên.

Các quy tắc cơ bản

  • Mọi thao tác thay đổi đều cần một header Idempotency-Key. Cùng khóa + cùng nội dung → cùng kết quả đã ghi nhận (cùng ID gửi đi). Cùng khóa + nội dung khác → 409 idempotency_conflict.
  • Việc chỉnh sửa và lên lịch cần expectedVersion; phiên bản cũ sẽ trả về 409 revision_conflict kèm phiên bản hiện tại trong error.details.currentVersion.
  • 202 từ đăng/lên lịch nghĩa là đã chấp nhận để gửi đi, không bao giờ là "đã đăng". Theo dõi kết quả bằng GET /posts/{id}, webhook của khách hàng, hoặc polling có giới hạn.
  • Giới hạn tốc độ là giới hạn tốc độ kỹ thuật theo không gian làm việc (60/120/240 req/phút theo gói; 429 + Retry-After). Không có hạn mức yêu cầu hay đăng bài: đăng bài không giới hạn trên mọi gói trả phí.
  • Lỗi dùng phong bì chuẩn hóa: { error: { code, message, fieldErrors?, destinationErrors?, retryable?, retryAfterSeconds?, requestId } }.

Từ đầu đến cuối: bản nháp → xác thực → đăng → quan sát

Ví dụ này yêu cầu Bash, curl, jq, Node 22+, một không gian làm việc đang hoạt động, một Trang Facebook hoặc điểm đến LinkedIn đã kết nối, và một khóa có accounts:read, posts:read, posts:write và posts:publish. Đặt ACCOUNT_ID thành một điểm đến được phép từ /accounts; kiểm tra hỗ trợ định dạng văn bản của nó trong /capabilities. Chạy lệnh đăng sẽ đăng nội dung thật.

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"

Với các điểm đến dạng ảnh/video, hãy tải lên và hoàn tất media trước, sau đó dùng các ID tài sản được trả về trong mediaIds và một định dạng điểm đến đủ điều kiện. Quan sát từng ID gửi đi từ phản hồi được chấp nhận; dùng webhook hoặc polling trạng thái có giới hạn kèm backoff. Một lần đọc trạng thái ngay lập tức vẫn có thể đang chờ.

Lên lịch thay vì đăng

Dùng thao tác này trên một bản nháp thay cho bước đăng ở trên. Lấy lại phiên bản hiện tại của nó sau bất kỳ lần chỉnh sửa nào. Thao tác này tính một thời điểm trong tương lai thay vì dùng một ngày mẫu sẽ hết hạn.

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"

Thời điểm phải nằm trong tương lai và trong phạm vi 90 ngày; thời điểm UTC và múi giờ hiển thị được lưu riêng. Nếu khóa API của bạn hết hạn vào hoặc trước thời điểm đó, phản hồi được chấp nhận sẽ bao gồm một mục warnings với mã key_expires_before_schedule. Lượt gửi vẫn được lên lịch, nhưng phải được xem xét và gửi lại dưới một chủ thể đang hoạt động trước khi có thể đăng. Cảnh báo này được giữ nguyên khi phát lại yêu cầu. Hủy trong khi công việc vẫn chưa được nhận an toàn:

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.

Chỉ thử lại điểm đến đã biết là thất bại (các trạng thái không rõ/thành công bị từ chối):

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

Media (tải lên trực tiếp)

Dữ liệu media không bao giờ đi qua API này.

# 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

Tệp là tạm thời: bài đăng đã lên lịch giữ media của mình cho đến khi đăng xong, và một giá trị deleteAfter động (hoặc null) luôn được hiển thị. Hãy giữ các bản gốc của bạn.

Sử dụng

GET /usage báo cáo gói, số chỗ tài khoản đã kết nối/đã đặt, số thành viên, dung lượng lưu trữ, phạm vi 90 ngày và thông tin tốc độ. Các con số hoạt động chỉ là chỉ số vận hành: không có bộ đếm bài đăng còn lại ở bất kỳ đâu trong sản phẩm.

Phân trang

Các endpoint liệt kê dùng con trỏ mờ: ?limit=25&cursor=<nextCursor>. Dấu thời gian là UTC ISO-8601. Tiếp tục cho đến khi nextCursor là null; một trang bài đăng đã lọc có thể trống trong khi con trỏ không null của nó vẫn trỏ đến các bản ghi cũ hơn còn cần quét. Ưu tiên webhook (xem webhooks) hoặc polling có giới hạn kèm backoff thay vì vòng lặp trạng thái dày đặc.

Giới hạn và thành công từng phần

Khả năng của điểm đến (từ GET /capabilities) mang giới hạn hiệu lực nghiêm ngặt nhất: ứng dụng, nhà cung cấp, mạng và tài khoản. Khi một giới hạn chặn yêu cầu, phong bì lỗi có thể hành động được:

{
  "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 và trial_expired là các phản hồi 402; không có gì bị xóa, và bản nháp/công việc trong hàng đợi được giữ lại cho sau khi nâng cấp.

Một lần đăng/lên lịch là một lô các công việc điểm đến độc lập. Thành công từng phần là bình thường và được báo cáo theo từng điểm đến: không bao giờ như một lời hứa nguyên tử:

{
  "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": "…"
}

Chỉ thử lại điểm đến thất bại (POST /deliveries/{id}/retry); các điểm đến thành công không bao giờ được gửi lại. Yêu cầu đồng ý/kết nối lại trả về requires_action với hướng dẫn an toàn, không bao giờ là bí mật.

Tài liệu tham khảo đầy đủ

Với TikTok, GET /accounts/{id}/tiktok/settings trả về các lựa chọn quyền riêng tư hiện tại của creator đã kết nối, quyền tương tác, giới hạn thời lượng và tính khả dụng của chế độ đăng. Nó yêu cầu accounts:read và tuân theo danh sách cho phép của khóa. Việc lưu bản nháp hoặc đọc các cài đặt này không cung cấp sự đồng ý.

Một lần đăng/lên lịch thiếu xác nhận của con người hiện tại sẽ trả về HTTP 409 consent_required với error.requiresAction.url trỏ đến bản nháp đã lưu trong trình soạn thảo đã xác thực. Phần xác thực có thể trả về cùng cơ chế chuyển giao cùng với các vấn đề có cấu trúc của nó. Người dùng sẽ xem xét chính xác video/chú thích và đưa ra các lựa chọn rõ ràng tại đó; khóa sản phẩm và MCP không thể xác nhận thay họ. Sau khi người dùng xác nhận, hãy thử lại qua dịch vụ đăng chung thông thường. Chỉnh sửa nội dung hoặc thay đổi định danh điểm đến đòi hỏi phải xem xét lại. URL chuyển giao không chứa khóa sản phẩm, token hay URL media đã ký và không cấp quyền truy cập cho người không có tư cách thành viên không gian làm việc. UUID không gian làm việc của nó xác định không gian làm việc của khóa; trình duyệt có một không gian làm việc được chọn khác phải chuyển đổi rõ ràng sau khi kiểm tra tư cách thành viên hiện tại trước khi xem bản nháp này.

Xem đặc tả OpenAPI để biết hợp đồng đầy đủ, hiện tại. UI, REST và MCP đều đọc cùng các dịch vụ, nên chúng áp dụng cùng quy tắc không gian làm việc. Kết quả phản ánh trạng thái hiện tại của từng yêu cầu; các yêu cầu riêng biệt có thể quan sát thấy các cập nhật xảy ra xen giữa.