Endpoint /v1/videos/generations: Το πρώτο σας βίντεο
Σε αυτήν τη σελίδα
Ενημερώθηκε στις 3 Νοεμβρίου 2026 με βάση την τεκμηρίωση βίντεο της xAI: διατίθενται τρία μοντέλα βίντεο (
grok-imagine-video-1.5, η έκδοση-liteκαι τοgrok-imagine-video), η ανάλυση φτάνει έως τα 1080p στα μοντέλα 1.5, τα βίντεο περιλαμβάνουν κομμάτι ήχου από προεπιλογή (generate_audio), τα όρια ρυθμού μετριούνται σε αιτήματα ανά δευτερόλεπτο και η παράμετροςsizeπου παρουσιαζόταν στην παλιά έκδοση δεν εμφανίζεται στην αναφορά API. Πηγές: Video Generation · Pricing.
Δημιουργία Βίντεο από Κείμενο
Το API της xAI εκθέτει ένα αφιερωμένο endpoint βίντεο, το POST /v1/videos/generations, το οποίο μετατρέπει μια γραπτή περιγραφή σε μια κινούμενη ακολουθία χρησιμοποιώντας ένα από τα τρία μοντέλα Grok Imagine Video. Σκεφτείτε το ως ένα στούντιο κατ’ απαίτηση: εσείς περιγράφετε μια σκηνή, το μοντέλο τη ζωντανεύει και εσείς ανακτάτε ένα αρχείο MP4 έτοιμο για επεξεργασία. Διαφημιστικά κλιπ, οπτικοποιήσεις εννοιών, επεξηγηματικά κινούμενα σχέδια—όλες αυτές οι περιπτώσεις χρήσης περνούν από αυτό το ίδιο endpoint, γι’ αυτό θα το αναλύσουμε πρώτο.
Το παραπάνω παράδειγμα σας δίνει μια ιδέα του αναμενόμενου αποτελέσματος. Πριν γράψετε το πρώτο σας αίτημα, λάβετε υπόψη τα τέσσερα όρια που καθορίζουν όλα όσα παράγετε με αυτά τα μοντέλα.
Δομή Αιτήματος
Το σώμα του αιτήματος είναι ένα αντικείμενο JSON ανακουφιστικής απλότητας. Δηλώνετε το μοντέλο, γράφετε την εντολή (prompt) σας και πλαισιώνετε το αποτέλεσμα με τρεις παραμέτρους μορφοποίησης.
{
"model": "grok-imagine-video",
"prompt": "A dolphin jumping in a sunset",
"duration": 5,
"aspect_ratio": "16:9",
"resolution": "720p"
}
Ακολουθεί η ακριβής σημασία κάθε πεδίου:
- model:
grok-imagine-video-1.5, το νεότερο, η οικονομική του έκδοσηgrok-imagine-video-1.5-lite, που προτείνεται από την xAI για απλά βίντεο, ήgrok-imagine-video, η προηγούμενη γενιά, που χρησιμοποιείται ακόμη στα παραδείγματα αυτού του μαθήματος - prompt: η περιγραφή κειμένου της επιθυμητής σκηνής
- duration: διάρκεια σε δευτερόλεπτα, μεταξύ 1 και 15 (8 από προεπιλογή)
- aspect_ratio: αναλογία εικόνας (16:9 από προεπιλογή, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3, 21:9, 5:2)
- resolution:
480p(προεπιλογή),720p, ή1080p—το τελευταίο αποδίδεται εγγενώς από τοgrok-imagine-video-1.5σε text-to-video και image-to-video, λαμβάνεται μέσω δειγματοληψίας ανώτερης ανάλυσης (upsampling) από τα 720p στην έκδοση-lite, και απουσιάζει από τοgrok-imagine-video, το οποίο σταματά στα 720p
Δύο σημεία αξίζουν έμφασης εδώ. Το μοντέλο grok-imagine-video κοστίζει $0.050 ανά δευτερόλεπτο δημιουργημένου βίντεο ($0.08 για το grok-imagine-video-1.5, $0.02 για την έκδοση -lite, με δεδομένα της 3ης Νοεμβρίου 2026): μια ακολουθία πέντε δευτερολέπτων σας κοστίζει επομένως $0.25 με το πρώτο, ανεξάρτητα από το πόσες προσπάθειες χρειάστηκαν για να φτάσετε εκεί. Και το όριο ρυθμού μετριέται σε αιτήματα ανά δευτερόλεπτο, ανάλογα με το επίπεδο της ομάδας σας: 10 στο επίπεδο εισαγωγής για μοντέλα βίντεο, ένα άνετο περιθώριο για κανονική χρήση, το οποίο γίνεται περιορισμός όταν εκτοξεύετε μαζικές παρτίδες.
Το σημαντικότερο είναι ότι η δημιουργία είναι ασύγχρονη. Η κλήση POST δεν επιστρέφει ένα βίντεο: επιστρέφει ένα request_id, και εναπόκειται σε εσάς να ελέγχετε την κατάσταση (polling) μέχρι να είναι έτοιμο το αρχείο. Αυτός ο μηχανισμός polling αποτελεί αντικείμενο ενός πλήρους μαθήματος αργότερα στην εκπαίδευση· προς το παρόν, απλώς θυμηθείτε ότι η άμεση απόκριση είναι μια επιβεβαίωση, όχι ένα αποτέλεσμα.
Μια Πρώτη Κλήση End-to-End
Ας περάσουμε στην πράξη με το curl. Το ακόλουθο αίτημα παραγγέλνει μια ακολουθία πέντε δευτερολέπτων σε 720p, οριζόντια μορφή.
curl -X POST "https://api.x.ai/v1/videos/generations" \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine-video",
"prompt": "A cat playing with a ball of yarn in a bright living room",
"duration": 5,
"aspect_ratio": "16:9",
"resolution": "720p"
}'
Η απόκριση χωράει σε μία γραμμή:
{
"request_id": "vid_abc123def456"
}
Φυλάξτε αυτόν τον αναγνωριστικό με ασφάλεια. Είναι ο μόνος τρόπος σας να ανακτήσετε το βίντεο μόλις ολοκληρωθεί η δημιουργία, και μια εφαρμογή που τον χάνει έχει πληρώσει για μια δημιουργία που δεν θα ανακτήσει ποτέ. Σε μια πραγματική υπηρεσία, τον καταγράφετε πριν καν ξεκινήσετε το polling.
Ήχος, από Προεπιλογή
Ένα δημιουργημένο βίντεο περιλαμβάνει ένα κομμάτι ήχου από προεπιλογή—με, στα grok-imagine-video-1.5 και την έκδοση -lite, ομιλία συγχρονισμένη με την κίνηση των χειλιών. Για ένα βίντεο χωρίς ήχο, που προορίζεται για παράδειγμα ως φόντο ιστότοπου ή για επεξεργασία όπου θα προσθέσετε τη δική σας μουσική, προσθέστε "generate_audio": false στο αίτημα.
Για να πλαισιώσετε την έξοδο, ωστόσο, το API γνωρίζει μόνο την αναλογία (aspect_ratio) και την ευκρίνεια (resolution): η αναφορά API δεν παρέχει καμία παράμετρο μεγέθους σε εικονοστοιχεία. Στο image-to-video, η αναλογία εξόδου ακολουθεί πάντα αυτή της εικόνας προέλευσης.
Βασικά σημεία
- Το endpoint είναι
POST /v1/videos/generations, μεgrok-imagine-video-1.5, την έκδοση-lite, ήgrok-imagine-video - Η διάρκεια κυμαίνεται από 1 έως 15 δευτερόλεπτα (8 από προεπιλογή), η ανάλυση από 480p έως 1080p (μέγιστο 720p με
grok-imagine-video) - Η τιμή υπολογίζεται ανά δημιουργημένο δευτερόλεπτο: $0.020 (
-lite), $0.050 (grok-imagine-video), ή $0.080 (grok-imagine-video-1.5) - Η δημιουργία είναι ασύγχρονη: λαμβάνετε ένα
request_idγια να κάνετε polling στη συνέχεια - Εννέα αναλογίες διαστάσεων είναι διαθέσιμες για προσαρμογή σε όλες τις μορφές
- Ένα κομμάτι ήχου δημιουργείται από προεπιλογή· το
"generate_audio": falseδίνει ένα βίντεο χωρίς ήχο