Ενσωμάτωση API

Video Translation API για λειτουργίες κυκλοφορίας πολλαπλών περιοχών

Τοπικοποιήστε ένα source video σε πολλαπλά έτοιμα για την αγορά outputs με αυτοματοποίηση βάσει κατάστασης, απομόνωση αποτυχιών σε επίπεδο locale και ελεγχόμενες ροές εργασίας rollout.

Πρόβλημα

Οι παγκόσμιες κυκλοφορίες συχνά αποτυγχάνουν στον συγχρονισμό, όχι στην ποιότητα μετάφρασης: η κύρια γλώσσα δημοσιεύεται πρώτη, ενώ οι περιφερειακές παραλλαγές καθυστερούν και ο χρονισμός της καμπάνιας διαταράσσεται.

Αποτέλεσμα με το Ssemble

Το Ssemble επιτρέπει λειτουργίες source-once, localize-many με παρακολούθηση κατάστασης ανά locale, ώστε οι ομάδες να κυκλοφορούν σε ελεγχόμενα κύματα και να ανακτούν γρήγορα τις μερικές αποτυχίες.

Βασικά στοιχεία υλοποίησης

Base URL: https://aiclipping.ssemble.com/api/v1

Αρχιτεκτονική ενσωμάτωσης (ingest → επεξεργασία → poll/webhook → δημοσίευση)

1) Ingest

Δημιουργήστε το manifest μετάφρασης: source, λίστα locales, πολιτική rollout και συμπεριφορά fallback.

2) Επεξεργασία

Υποβάλετε create requests ανά locale και διατηρήστε ένα parent release id για ιχνηλασιμότητα από άκρο σε άκρο.

3) Poll / Webhook

Παρακολουθήστε την κατάσταση κάθε locale ανεξάρτητα, για να εντοπίζετε γρήγορα σενάρια μερικής επιτυχίας και μερικής αποτυχίας.

4) Δημοσίευση

Κυκλοφορήστε τα locales που περνούν τις πύλες QA/πολιτικής και βάλτε ξανά στην ουρά τα αποτυχημένα locales με φραγμένη στρατηγική retry.

Παραδείγματα endpoint

POST /shorts/create— Δημιουργία εργασιών επεξεργασίας ανά locale
GET /shorts/:id/status— Παρακολούθηση της κατάστασης κύκλου ζωής κάθε locale
GET /shorts/:id— Ανάκτηση του ολοκληρωμένου τοπικοποιημένου output για κυκλοφορία

Οδηγίες ελέγχου ταυτότητας

Διατηρήστε τα API keys και τα controls rollout μόνο στις backend υπηρεσίες. Διαχωρίστε τα κλειδιά ανά περιβάλλον και περιορίστε αυστηρά την πρόσβαση rollout παραγωγής.

Όρια ρυθμού (rate limits) και επαναλήψεις (retries)

Βάλτε τις υποβολές locale σε ελεγχόμενα batches, όχι σε πλήρεις εκρήξεις fan-out. Χρησιμοποιήστε exponential backoff σε 429/5xx και θέστε ανώτατο όριο στα retries.

Παράδειγμα αιτήματος

POST /shorts/create
{
  "fileUrl": "https://cdn.example.com/master-campaign.mp4",
  "start": 30,
  "end": 420,
  "language": "ko",
  "captionLanguage": "ja",
  "preferredLength": "under60sec",
  "layout": "auto"
}

Παράδειγμα απόκρισης

200 OK
{
  "data": {
    "requestId": "665a1b2c3d4e5f6a7b8c9d0e",
    "status": "processing",
    "creditsUsed": 1,
    "estimatedCompletionTime": "2026-03-10T07:00:00.000Z"
  }
}

Παράδειγμα σεναρίου σφάλματος

500 Internal Server Error
{
  "error": {
    "code": "internal_error",
    "message": "An internal error occurred. Please try again.",
    "details": null
  }
}

Έκδοση (versioning)

Καταγράφετε τα metadata schema/version για κάθε αίτημα locale, ώστε οι παλινδρομήσεις μεταξύ locales να είναι διαγνώσιμες μετά από αλλαγές στο API.

Υποστήριξη

Διατηρήστε parent release id + locale + requestId σε κάθε μετάβαση κατάστασης για γρήγορη ανάκτηση από περιστατικά μερικής κυκλοφορίας.

Γρήγορη εκκίνηση

Ορίστε τον πίνακα locales και τη στρατηγική rollout στη backend διαμόρφωση.
Δημιουργήστε ένα αίτημα επεξεργασίας ανά locale χρησιμοποιώντας τα πεδία language/captionLanguage.
Κάντε poll την κατάσταση και ενημερώστε το release board μέχρι κάθε locale να φτάσει σε τερματική κατάσταση.
Ανακτήστε τα ολοκληρωμένα outputs και εκτελέστε ελέγχους QA ανά locale.
Δημοσιεύστε αμέσως τα locales που περνούν και δρομολογήστε τα αποτυχημένα locales σε φραγμένη ουρά retry.

Άνοιγμα τεκμηρίωσης ροής εργασίας μετάφρασης

Ξεκινήστε την ενσωμάτωση

1) Έλεγχος ταυτότητας

Μοτίβα API key μόνο για server

2) Κύκλος ζωής κατάστασης

Μοντέλο queued/processing/completed/failed

3) Στρατηγική rate-limit

Headers, παράθυρα reset και πειθαρχία polling

4) Ταξινομία σφαλμάτων

Προγραμματιστικός χειρισμός ανά error.code

Ροή εργασίας 3 βημάτων

Κάντε ingest ένα source asset με τον πίνακα των locales-στόχων και την πολιτική rollout.
Επεξεργαστείτε τις εργασίες locale ασύγχρονα με ανεξάρτητη παρακολούθηση κατάστασης ανά locale.
Δημοσιεύστε τα ολοκληρωμένα locales μέσω περιφερειακών ουρών, ενώ τα αποτυχημένα locales δρομολογούνται σε ελεγχόμενα retries.

Γιατί οι ομάδες επιλέγουν το Ssemble

Σχεδιασμένο για ομάδες περιφερειακών καναλιών, όπου ο συντονισμός κυκλοφορίας είναι εξίσου κρίσιμος με την ποιότητα περιεχομένου.
Απομονώνει τις αποτυχίες ανά locale, ώστε ένα ζήτημα να μην μπλοκάρει ολόκληρες κυκλοφορίες καμπανιών.
Λειτουργεί με αυτοματοποίηση δημοσίευσης για ροές εργασίας διανομής follow-the-sun.

Επόμενο βήμα

Άνοιγμα quickstart του translation API Δείτε τις τιμές Τεκμηρίωση για προγραμματιστές

Συχνές ερωτήσεις

Πώς αποτρέπουμε ένα locale από το να μπλοκάρει όλες τις περιοχές;

Χρησιμοποιήστε μηχανές κατάστασης ανά locale και πύλες κυκλοφορίας, ώστε κάθε locale να μπορεί να δημοσιεύεται ανεξάρτητα, εκτός εάν η πολιτική απαιτεί συγχρονισμό όλων των locales.

Πρέπει να υποβάλουμε όλα τα locales ταυτόχρονα;

Συνήθως όχι. Το ελεγχόμενο batching προστατεύει τα rate budgets και απλοποιεί το triage περιστατικών όταν μια διαδρομή locale υποβαθμιστεί.

Ποιο είναι το ελάχιστο payload observability;

Παρακολουθήστε parent release id, κωδικό locale, requestId, μεταβάσεις κατάστασης, error code και retry count για κάθε εργασία.

Ποια σφάλματα πρέπει να κάνουν retry αυτόματα;

Κάντε retry σε παροδικά σφάλματα transport, 429 και 5xx με backoff. Αποτύχετε γρήγορα σε σφάλματα επικύρωσης και δρομολογήστε για διόρθωση config/δεδομένων.

Μπορούν η μετάφραση και η δημοσίευση να διαχωριστούν;

Ναι. Πολλές ομάδες κρατούν την ολοκλήρωση της μετάφρασης και τη δημοσίευση στα κανάλια σε ξεχωριστές ουρές για καλύτερο έλεγχο και ασφάλεια rollback.

Εγγυάται αυτό ίσα αποτελέσματα σε όλα τα locales;

Δεν πρέπει να υποτίθεται καμία εγγύηση. Μετρήστε τον χρόνο ολοκλήρωσης, το ποσοστό αποτυχίας και το ποσοστό επιτυχίας QA ανά locale και προσαρμόστε την πολιτική rollout ανάλογα.