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 चाहिए; पुराना वर्ज़न 409 revision_conflict लौटाता है, जिसमें वर्तमान वर्ज़न error.details.currentVersion में होता है।
  • पब्लिश/शेड्यूल से 202 का अर्थ है डिस्पैच के लिए स्वीकृत, कभी भी "प्रकाशित" नहीं। परिणामों को GET /posts/{id}, ग्राहक वेबहुक, या बाउंडेड पोलिंग से ट्रैक करें।
  • रेट लिमिट प्रति वर्कस्पेस तकनीकी गति सीमाएँ हैं (प्लान के अनुसार 60/120/240 req/min; 429 + Retry-After)। कोई रिक्वेस्ट या पोस्टिंग कोटा नहीं है: हर पेड प्लान पर पोस्टिंग असीमित है।
  • एरर नॉर्मलाइज़्ड एनवेलप का उपयोग करते हैं: { error: { code, message, fieldErrors?, destinationErrors?, retryable?, retryAfterSeconds?, requestId } }।

एंड-टू-एंड: ड्राफ़्ट → सत्यापन → प्रकाशन → निगरानी

इस उदाहरण के लिए Bash, curl, jq, Node 22+, एक सक्रिय वर्कस्पेस, जुड़ा हुआ Facebook Page या 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 देखें; वेबहुक या बैकऑफ़ के साथ बाउंडेड स्टेटस पोल का उपयोग करें। एक तुरंत स्टेटस रीड अभी भी पेंडिंग हो सकती है।

पब्लिश के बजाय शेड्यूल करें

इसे ऊपर के पब्लिश चरण के बजाय ड्राफ़्ट पर उपयोग करें। किसी भी एडिट के बाद उसका वर्तमान वर्ज़न फिर से लाएँ। यह समाप्त होने वाली सैंपल तारीख की जगह भविष्य का क्षण (instant) गणना करता है।

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 कर्सर पुराने रिकॉर्ड्स की ओर इशारा करता है जिन्हें अभी स्कैन करना है। तंग स्टेटस लूप की जगह वेबहुक (वेबहुक देखें) या बैकऑफ़ के साथ बाउंडेड पोलिंग प्राथमिकता दें।

सीमाएँ और आंशिक सफलता

गंतव्य कैपेबिलिटीज़ (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 वही सेवाएँ पढ़ते हैं, इसलिए वे वही वर्कस्पेस नियम लागू करते हैं। परिणाम प्रत्येक रिक्वेस्ट की वर्तमान स्थिति दर्शाते हैं; अलग रिक्वेस्ट बीच के अपडेट देख सकते हैं।