xAI SDK και Αυτόματη Επαναληπτική Λήψη (Polling)
Σε αυτήν τη σελίδα
Ενημερώθηκε στις 2 Νοεμβρίου 2026 με βάση την τεκμηρίωση βίντεο της xAI και τον κώδικα
xai-sdk1.21.0: οι μέθοδοι ονομάζονταιclient.video.generateκαιclient.video.extend(η επεξεργασία χρησιμοποιεί τοgenerateμεvideo_url), το αποτέλεσμα εκθέτει τοurl, η καθυστέρηση ορίζεται μέσω ενόςtimedeltaκαι το προεπιλεγμένο διάστημα επαναληπτικής λήψης είναι ένα δευτερόλεπτο. Τοawaitαπαιτεί τον ασύγχρονο πελάτηAsyncClientκαι η εξαίρεσηVideoGenerationErrorεισάγεται από τοxai_sdk.video. Η παλιά έκδοση καλούσε μεθόδους και μια ενότητα εξαιρέσεων που δεν υπάρχουν. Πηγές: Δημιουργία Βίντεο · Επεξεργασία Βίντεο · Επέκταση Βίντεο · xai-sdk-python.
Απλοποιήστε την επαναληπτική λήψη με το SDK
Το προηγούμενο μάθημα σας ζήτησε να γράψετε έναν βρόχο επαναληπτικής λήψης (polling loop) χειροκίνητα. Είναι μια χρήσιμη άσκηση για να κατανοήσετε τον κύκλο ζωής της δημιουργίας, αλλά αποτελούν επίσης τριάντα γραμμές κώδικα που πρέπει να συντηρείτε σε κάθε έργο, με τη δική τους διαχείριση χρονικού ορίου, περιπτώσεις αποτυχίας και μετατροπές κατάστασης. Το επίσημο Python SDK της xAI (pip install xai-sdk) ενσωματώνει τα πάντα: υποβάλλετε το αίτημα και αυτό διαχειρίζεται την αναμονή.
Μία κλήση αντί για έναν βρόχο
Η μέθοδος client.video.generate ομαδοποιεί την υποβολή, την παρακολούθηση και την ανάκτηση. Επιστρέφει τον έλεγχο μόνο όταν το βίντεο είναι έτοιμο ή εγείρει μια εξαίρεση εάν κάτι πήγε στραβά.
import os
import xai_sdk
client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))
# Δημιουργία κειμένου-σε-βίντεο με αυτόματη επαναληπτική λήψη
video = client.video.generate(
prompt="A sunrise over the Alps, accelerated time-lapse",
model="grok-imagine-video-1.5",
duration=5,
aspect_ratio="16:9",
resolution="720p",
)
print(video.url)
print(f"Duration: {video.duration} s, model: {video.model}")
Πίσω από αυτές τις λίγες γραμμές, το SDK κάνει ακριβώς ό,τι κωδικοποιήσατε προηγουμένως: υποβολή του αιτήματος, επαναληπτικός έλεγχος της κατάστασης κάθε δευτερόλεπτο από προεπιλογή και, στη συνέχεια, επιστροφή του αποτελέσματος ή εγερση εξαίρεσης ανάλογα με το αποτέλεσμα.
Μια ρύθμιση αξίζει την προσοχή σας αμέσως από την ανάπτυξη: από προεπιλογή, το SDK περιμένει έως και 10 λεπτά πριν τα παρατήσει. Αυτό είναι άνετο για ένα script παραγωγής νυχτερινής λειτουργίας, αλλά πολύ μεγάλο για ένα αίτημα ιστού όπου ένας χρήστης περιμένει μια απάντηση. Οι παράμετροι timeout και interval, και τα δύο αντικείμενα timedelta, ορίζουν το όριο και τον ρυθμό:
from datetime import timedelta
video = client.video.generate(
prompt="Your description",
model="grok-imagine-video-1.5",
duration=10,
timeout=timedelta(minutes=5), # 5 λεπτά το μέγιστο
interval=timedelta(seconds=5), # ένας έλεγχος κάθε 5 δευτερόλεπτα
)
Εάν θέλετε να διατηρήσετε τον έλεγχο της αναμονής—για να μεταδώσετε την πρόοδο, για παράδειγμα—το client.video.start υποβάλλει το αίτημα και επιστρέφει το request_id του, το οποίο το client.video.get στη συνέχεια ερωτά.
Διαχείριση σφαλμάτων στην πηγή
Το SDK διακρίνει τις αποτυχίες, γλιτώνοντάς σας από την ανάλυση συμβολοσειρών για να καταλάβετε τι συνέβη:
from xai_sdk.video import VideoGenerationError
try:
video = client.video.generate(
prompt="Your description",
model="grok-imagine-video-1.5",
duration=5,
)
print(f"Video ready: {video.url}")
except VideoGenerationError as e:
print(f"Generation failed [{e.code}]: {e.message}")
except TimeoutError:
print("Timeout exceeded: increase the timeout or simplify the request")
Κάθε σφάλμα απαιτεί διαφορετική αντίδραση και η σύγχυσή τους οδηγεί σε άχρηστους βρόχους επανάληψης ή, χειρότερα, σε χρεώσιμες δημιουργίες που δεν αποδίδουν τίποτα.
| Σφάλμα | Αιτία | Συνιστώμενη ενέργεια |
|---|---|---|
VideoGenerationError | Αποτυχία που σηματοδοτείται από το API: απόρριψη prompt, μη έγκυρη πηγή, υπερφόρτωση υπηρεσίας… (code, message) | Διαβάστε τον κωδικό: διορθώστε το αίτημα ή δοκιμάστε ξανά αργότερα εάν η υπηρεσία δεν ήταν διαθέσιμη |
TimeoutError | Υπέρβαση του χρόνου αναμονής στην πλευρά του πελάτη | Αυξήστε το timeout ή μειώστε τη διάρκεια |
RuntimeError | Το αναβληθέν αίτημα έληξε ή ολοκληρώθηκε χωρίς αποτέλεσμα | Επανεκκινήστε τη δημιουργία |
grpc.RpcError | Σφάλμα μεταφοράς SDK, συμπεριλαμβανομένων των ορίων ρυθμού (κωδικός RESOURCE_EXHAUSTED) και προβλημάτων κλειδιού | Απομακρύνετε τα αιτήματα με backoff ή ελέγξτε το κλειδί |
Το SDK χρησιμοποιεί gRPC: ένα ξεπερασμένο όριο ρυθμού δεν εμφανίζεται εδώ ως κωδικός HTTP 429, αλλά ως grpc.RpcError με κωδικό RESOURCE_EXHAUSTED.
Επεξεργασία και επέκταση, ίδια ευκολία
Η επεξεργασία δεν έχει αφιερωμένη μέθοδο: είναι το generate με ένα βίντεο προέλευσης, που περνιέται ως video_url (βίντεο έως 8,7 δευτερόλεπτα, ίδια διάρκεια εξόδου, μέγιστο 720p).
video = client.video.generate(
prompt="Transform the scene into Japanese anime style",
model="grok-imagine-video",
video_url="https://example.com/video.mp4",
)
Η επέκταση παρατείνει μια ακολουθία 2 έως 15 δευτερολέπτων κατά ένα τμήμα 2 έως 10 δευτερολέπτων και επιστρέφει το πλήρες βίντεο:
video = client.video.extend(
prompt="Continue the scene with a pan to the right",
model="grok-imagine-video",
video_url="https://example.com/video.mp4",
duration=5,
)
Σημειώστε τη διαφορά με το REST API: το SDK λαμβάνει το βίντεο ως παράμετρο video_url, ενώ το σώμα JSON αναμένει ένα αντικείμενο video με την ιδιότητά του url.
Μην αφήνετε ποτέ ένα βίντεο στο cloud
Το SDK δεν αλλάζει τίποτα σχετικά με τον προσωρινό χαρακτήρα των URL αποτελεσμάτων. Εάν ο κώδικάς σας απλώς εμφανίζει το video.url, πληρώσατε για μια δημιουργία που σύντομα θα εξαφανιστεί. Η βέλτιστη πρακτική είναι να αλυσοδεύετε τη δημιουργία και τη λήψη στην ίδια συνάρτηση, ώστε να καθίσταται αδύνατο να ξεχάσετε το βήμα.
from pathlib import Path
import httpx
async def generate_and_save(client, prompt, output_file, **options):
"""Δημιουργεί ένα βίντεο και το αποθηκεύει τοπικά (client: xai_sdk.AsyncClient)."""
video = await client.video.generate(
prompt=prompt,
model="grok-imagine-video-1.5",
**options,
)
# Άμεση λήψη
async with httpx.AsyncClient() as http:
response = await http.get(video.url)
response.raise_for_status()
Path(output_file).write_bytes(response.content)
print(f"Video saved: {output_file}")
return output_file
Για αποθήκευση χωρίς διέλευση μέσω του διακομιστή σας, η παράμετρος storage_options της δημιουργίας εναποθέτει το βίντεο στο xAI Files API, με λήξη της επιλογής σας.
Δημιουργία πολλαπλών βίντεο ταυτόχρονα
Με τον ασύγχρονο πελάτη, κάθε κλήση είναι μια συνημιτία (coroutine) και το asyncio.gather εκκινεί ολόκληρη μια παρτίδα παράλληλα. Η επιλογή return_exceptions=True είναι καθοριστική εδώ: χωρίς αυτήν, ένα μόνο απορριφθέν αίτημα θα απέτυχε ολόκληρη την παρτίδα και θα χάνατε τα αποτελέσματα που είχαν ήδη ληφθεί.
import asyncio
import os
import xai_sdk
async def parallel_generation(requests):
"""Δημιουργεί πολλαπλά βίντεο παράλληλα."""
client = xai_sdk.AsyncClient(api_key=os.getenv("XAI_API_KEY"))
tasks = [
client.video.generate(
prompt=req["prompt"],
model="grok-imagine-video-1.5",
duration=req.get("duration", 5),
aspect_ratio=req.get("aspect_ratio", "16:9"),
)
for req in requests
]
results = await asyncio.gather(*tasks, return_exceptions=True)
for i, res in enumerate(results, 1):
if isinstance(res, Exception):
print(f"Request {i} failed: {res}")
else:
print(f"Request {i} completed: {res.url}")
return results
Δύο δικλείδες ασφαλείας πλαισιώνουν αυτή την παραλληλοποίηση. Οι υποβολές καταναλώνουν το όριο ρυθμού σας, το οποίο μετριέται σε αιτήματα ανά δευτερόλεπτο ανάλογα με το επίπεδο της ομάδας σας (10 στο επίπεδο εισόδου για μοντέλα βίντεο): για μια μεγάλη παρτίδα, περιορίστε τον συγχρονισμό με ένα asyncio.Semaphore. Θυμηθείτε επίσης τι κάνει και τι δεν κάνει ο παραλληλισμός: δεν επιταχύνει καμία μεμονωμένη δημιουργία, μειώνει μόνο τον συνολικό χρόνο της παρτίδας.
Πρέπει να εγκαταλείψετε τη χειροκίνητη επαναληπτική λήψη;
Όχι συστηματικά. Η ακόλουθη σύγκριση δείχνει πού υπερέχει κάθε προσέγγιση.
| Πτυχή | Χειροκίνητη επαναληπτική λήψη | SDK |
|---|---|---|
| Πολυπλοκότητα | Υψηλή | Χαμηλή |
| Διαχείριση σφαλμάτων | Προς υλοποίηση | Ενσωματωμένη |
| Χρονικό όριο (Timeout) | Προς υλοποίηση | 10 λεπτά προεπιλογή, ρυθμιζόμενο |
| Διάστημα επαναληπτικής λήψης | Προς επιλογή | 1 δλ προεπιλογή, ρυθμιζόμενο |
| Ευελιξία | Ολική | Τυπική (ή start και get) |
| Εξάρτηση | Καμία | xAI SDK |
Η χειροκίνητη επαναληπτική λήψη διατηρεί τη συνάφειά της σε δύο καταστάσεις: όταν χρειάζεστε λεπτομερή έλεγχο, για παράδειγμα για να μεταδώσετε την πρόοδο σε μια διεπαφή πραγματικού χρόνου ή να την ενσωματώσετε σε ένα υπάρχον σύστημα ουράς, και όταν το πλαίσιο ανάπτυξής σας απαγορεύει την προσθήκη μιας επιπλέον εξάρτησης.
Βασικά σημεία
- Το
client.video.generateυποβάλλει, περιμένει και επιστρέφει το βίντεο (url,duration,model); χρονικό όριο 10 λεπτών και έλεγχος ανά δευτερόλεπτο από προεπιλογή - Η επεξεργασία χρησιμοποιεί το
generateμεvideo_url, η επέκταση χρησιμοποιεί τοclient.video.extend - Τα
VideoGenerationError(από τοxai_sdk.video),TimeoutErrorκαιRuntimeErrorδιακρίνουν τις αποτυχίες· τα όρια ρυθμού φτάνουν ωςgrpc.RpcError - Να κατεβάζετε πάντα το βίντεο αμέσως μετά τη δημιουργία (προσωρινά URL)
- Ο ασύγχρονος πελάτης και το
asyncio.gatherπαραλληλοποιούν μια παρτίδα, εντός του ορίου ρυθμού του επιπέδου σας