Μετάβαση στο κύριο περιεχόμενο
Ελληνικά— Επιλέξτε γλώσσα
Μενού

Ροή εργασίας ασύγχρονου τύπου και περιοδικός έλεγχος

Μάθημα 10 / 12 Ενημερώθηκε 2 Νοεμβρίου 2026 Μέσου επιπέδου
Σε αυτήν τη σελίδα
  1. Κατανόηση του κύκλου ζωής του βίντεο
  2. Έλεγχος κατάστασης δημιουργίας
  3. Τρεις καταστάσεις, τρεις ενέργειες
  4. Υλοποίηση περιοδικού ελέγχου (Polling)
  5. Ορισμός του διαστήματος περιοδικού ελέγχου
  6. Βασικά σημεία

Ενημερώθηκε στις 2 Νοεμβρίου 2026. Με βάση την αναφορά του xAI Video API: η διεύθυνση URL βρίσκεται στο πεδίο video.url (όχι στο video_url), μια δημιουργία έχει μόνο τρεις καταστάσεις (pending, done, failed, με την τελευταία να συνοδεύεται από κωδικό σφάλματος), και τα όρια ρυθμού εκφράζονται σε αιτήματα ανά δευτερόλεπτο με βάση το επίπεδο της ομάδας. Πηγές: Video Generation · Videos Reference · Rate limits.

Κατανόηση του κύκλου ζωής του βίντεο

Όλες οι λειτουργίες βίντεο στο xAI API είναι ασύγχρονες, και αυτό το χαρακτηριστικό διαμορφώνει την αρχιτεκτονική της εφαρμογής σας περισσότερο από όσο ίσως αναμένετε αρχικά. Μια κλήση chat ή η δημιουργία εικόνας επιστρέφει ένα αποτέλεσμα άμεσα· η δημιουργία βίντεο, ωστόσο, απαιτεί σημαντικό χρόνο επεξεργασίας και επιστρέφει μόνο μια επιβεβαίωση. Εναπόκειται σε εσάς να υλοποιήσετε την παρακολούθηση: να κάνετε περιοδικά ερωτήματα για την κατάσταση της εργασίας, να εντοπίζετε την ολοκλήρωση και να ανακτάτε το αρχείο. Ο πλήρης κύκλος αποτελείται από τέσσερα βήματα.

1

Υποβολή αιτήματος

POST στο endpoint δημιουργίας, επεξεργασίας ή επέκτασης. Άμεση απόκριση με ένα request_id.

2

Περιοδικός έλεγχος κατάστασης

GET /v1/videos/{request_id} σε τακτά χρονικά διαστήματα. Το πεδίο progress από 0 έως 100.

3

Ανάκτηση αποτελέσματος

Όταν η κατάσταση είναι done (progress = 100), η διεύθυνση URL του βίντεο είναι διαθέσιμη.

4

Άμεση λήψη

Η διεύθυνση URL του βίντεο είναι προσωρινή. Κατεβάστε το το συντομότερο δυνατό.

Έλεγχος κατάστασης δημιουργίας

Η παρακολούθηση περιλαμβάνει ένα απλό αίτημα GET στο endpoint κατάστασης, χρησιμοποιώντας το αναγνωριστικό που λάβατε κατά την υποβολή.

curl "https://api.x.ai/v1/videos/vid_abc123def456" \
  -H "Authorization: Bearer $XAI_API_KEY"

Η απόκριση εκθέτει τις ακόλουθες χρήσιμες πληροφορίες:

  • status : η τρέχουσα κατάσταση της δημιουργίας
  • progress : ένας ακέραιος από 0 έως 100 που υποδεικνύει την πρόοδο
  • video.url : η διεύθυνση URL του βίντεο, μέσα στο αντικείμενο video που υπάρχει όταν η κατάσταση είναι done, μαζί με τη διάρκειά του (video.duration)
  • video.respect_moderation : μια boolean τιμή που υποδεικνύει εάν το περιεχόμενο συμμορφώνεται με την πολιτική διαμεσολάβησης
  • error : σε περίπτωση αποτυχίας, ένας κωδικός (invalid_argument, permission_denied, failed_precondition, service_unavailable, ή internal_error) και ένα μήνυμα
  • usage.cost_in_usd_ticks : το κόστος του αιτήματος, σε δισεκατομμυριοστά του δολαρίου

Το πεδίο progress αξίζει μια σημείωση: δεν καθοδηγεί τη λογική ελέγχου σας, η οποία πρέπει πάντα να βασίζεται στο status, αλλά είναι πολύτιμο για μια διεπαφή χρήστη. Η εμφάνιση του «62%» αντί για έναν στατικό δείκτη φόρτωσης αλλάζει πλήρως την αντίληψη μιας αναμονής που μπορεί να διαρκέσει αρκετά λεπτά.

Τρεις καταστάσεις, τρεις ενέργειες

ΚατάστασηΠρόοδοςΣημασία
pending0-99Η δημιουργία είναι σε εξέλιξη
done100Ολοκληρώθηκε, η URL είναι διαθέσιμη
failedαπόνΗ δημιουργία απέτυχε

Εφόσον η κατάσταση είναι pending, η δημιουργία συνεχίζεται: απλώς συνεχίζετε να κάνετε ερωτήματα σε τακτά χρονικά διαστήματα, μεταβιβάζοντας την progress στη διεπαφή σας. Όταν αλλάξει σε done, το βίντεο είναι έτοιμο και το μόνο που απομένει είναι να διαβάσετε το video.url και να κατεβάσετε το αρχείο αμέσως—αυτές οι διευθύνσεις URL είναι προσωρινές και η τεκμηρίωση δεν καθορίζει τη διάρκεια ζωής τους, γεγονός που απαγορεύει την αποθήκευσή τους σε βάση δεδομένων για μετέπειτα χρήση.

Τέλος, η κατάσταση failed υποδεικνύει αποτυχία παραγωγής και το πεδίο error σας λέει ποια είναι αυτή. Η διάκριση έχει σημασία για τη συνέχεια: το service_unavailable (υπηρεσία προσωρινά υπερφορτωμένη) ή το internal_error δικαιολογούν την επανάληψη αργότερα, ενώ το invalid_argument ή το permission_denied—απορριφθείσα εντολή, μη έγκυρη εικόνα ή βίντεο προέλευσης—απαιτούν πρώτα τη διόρθωση του αιτήματος. Το Python SDK, από την πλευρά του, σηματοδοτεί επίσης μέσω σφάλματος ένα αναβληθέν αίτημα που έληξε πριν ανακτηθεί.

Υλοποίηση περιοδικού ελέγχου (Polling)

Η σύγχρονη έκδοση χωράει σε μία μόνο συνάρτηση. Εκτελεί βρόχο μέχρι τη λήξη του χρονικού ορίου, εξέρχεται νωρίς σε περίπτωση αποτυχίας εγείροντας τον κωδικό της και επιστρέφει τη διεύθυνση URL μόλις το βίντεο είναι έτοιμο.

import httpx
import time

def attendre_video(request_id, api_key, timeout=600, intervalle=5):
    """Αναμονή για την ολοκλήρωση της δημιουργίας βίντεο."""
    headers = {"Authorization": f"Bearer {api_key}"}
    debut = time.time()

    while time.time() - debut < timeout:
        resp = httpx.get(
            f"https://api.x.ai/v1/videos/{request_id}",
            headers=headers
        ).json()

        status = resp.get("status")
        progress = resp.get("progress", 0)

        if status == "done":
            return resp["video"]["url"]
        elif status == "failed":
            erreur = resp.get("error", {})
            raise RuntimeError(f"Η δημιουργία απέτυχε [{erreur.get('code')}] : {erreur.get('message')}")

        print(f"Σε εξέλιξη... {progress}%")
        time.sleep(intervalle)

    raise TimeoutError(f"Λήξη χρονικού ορίου μετά από {timeout} δευτερόλεπτα")

Σε μια υπηρεσία που διαχειρίζεται πολλαπλά αιτήματα ταυτόχρονα, αυτή η αποκλειστική έκδοση γίνεται σημείο συμφόρησης: κάθε αναμονή ακινητοποιεί ένα νήμα για λεπτά. Η ασύγχρονη μεταφορά ελευθερώνει τον βρόχο γεγονότων μεταξύ των ερωτημάτων και σας επιτρέπει να παρακολουθείτε δεκάδες δημιουργίες παράλληλα.

import httpx
import asyncio

async def attendre_video_async(request_id, api_key, timeout=600, intervalle=5):
    """Ασύγχρονη έκδοση του περιοδικού ελέγχου."""
    headers = {"Authorization": f"Bearer {api_key}"}
    async with httpx.AsyncClient() as client:
        debut = asyncio.get_event_loop().time()

        while asyncio.get_event_loop().time() - debut < timeout:
            resp = await client.get(
                f"https://api.x.ai/v1/videos/{request_id}",
                headers=headers
            )
            data = resp.json()

            if data["status"] == "done":
                return data["video"]["url"]
            elif data["status"] == "failed":
                raise RuntimeError(f"Η δημιουργία απέτυχε : {data.get('error')}")

            await asyncio.sleep(intervalle)

    raise TimeoutError("Λήξη χρονικού ορίου")

Ορισμός του διαστήματος περιοδικού ελέγχου

Η επιλογή του διαστήματος εξισορροπεί την ανταπόκριση έναντι των wasted αιτημάτων. Τα πέντε δευτερόλεπτα αποτελούν μια καλή συμβιβαστική λύση στις περισσότερες περιπτώσεις. Για μεγάλες δημιουργίες—δέκα έως δεκαπέντε δευτερόλεπτα βίντεο—δέκα έως δεκαπέντε δευτερόλεπτα μεταξύ των ελέγχων αρκούν και μειώνουν την κίνηση. Αντιθέτως, μια διαδραστική εφαρμογή όπου ο χρήστης παρακολουθεί μια μπάρα προόδου δικαιολογεί τη μείωση στα δύο ή τρία δευτερόλεπτα. Κάτω από το ένα δευτερόλεπτο, ωστόσο, δεν θα επιταχύνετε τίποτα: η δημιουργία προχωρά με τον δικό της ρυθμό και εσείς απλώς πολλαπλασιάζετε τα αιτήματα μάταια.

Βασικά σημεία

  • Όλες οι λειτουργίες βίντεο είναι ασύγχρονες: POST για υποβολή, GET για ανάκτηση
  • Τρεις πιθανές καταστάσεις: pending, done, failed (με κωδικό σφάλματος)
  • Το πεδίο progress (0-100) σας επιτρέπει να παρακολουθείτε την πρόοδο
  • Υλοποιήστε ένα χρονικό όριο και ένα διάστημα περιοδικού ελέγχου κατάλληλο για την περίπτωση χρήσης σας
  • Οι διευθύνσεις URL των βίντεο είναι προσωρινές: κατεβάστε τες αμέσως