API-Referenz
Grok Imagine Text zu Video
Verwenden Sie den Endpunkt „Text zu Video", um einen asynchronen Task zu erstellen.
01
Übersicht
Verwenden Sie den Endpunkt „Text zu Video" mit einem unterstützten Modell. Verwenden Sie die zurückgegebene Task-ID, um den Status abzurufen, oder geben Sie callback_url für die unten dokumentierten Zustellungen an.
Schnellstart
- Erstellen Sie einen API-Schlüssel und setzen Sie ihn als RUNAPI_API_KEY.
- Wählen Sie ein unterstütztes Modell und senden Sie eine POST-Anfrage, deren Body dem Schema dieses Modells entspricht.
- Speichern Sie die zurückgegebene Task-ID und fragen Sie den Status ab, bis ein Endzustand erreicht ist, oder verarbeiten Sie die unten dokumentierten Callbacks.
Endpunkt
- Basis-URL
https://runapi.ai- API-Version
v1- Authentifizierung
Authorization: Bearer YOUR_API_TOKEN
02
Unterstützte Modelle
Öffnen Sie eine Modellseite für aktuelle Preise, Ratenlimits und Details zur kommerziellen Nutzung.
03
JSON-BodyAnfrage-Schema
Felder und zulässige Werte hängen vom ausgewählten Modell ab. Wenn angegeben, empfängt callback_url die unten dokumentierten Task-Zustellungen.
grok-imagine-text-to-video8 Felder
aspect_ratiostring
Optional
Ausgabe-Seitenverhältnis.
Zulässige Werte:2:3, 3:2, 1:1, 16:9, 9:16
callback_urlstring
Optional
Webhook-URL für die terminale Task-Zustellung.
duration_secondsinteger
Optional
Ausgabedauer in Sekunden.
Bereich:6 - 30
enable_safety_checkerboolean
Optional
Inhaltssicherheitsprüfungen aktivieren.
modelstring
Erforderlich
Modell-Slug.
motion_stylestring
Optional
Bewegungsstil des Videos.
Zulässige Werte:fun, normal, spicy
output_resolutionstring
Optional
Ausgabeauflösung.
Zulässige Werte:480p, 720p
Standard: 480p
promptstring
Erforderlich
Prompt zur Videogenerierung.
Grenzwert:5000
grok-imagine-video-1.5-fast7 Felder
aspect_ratiostring
Optional
Ausgabe-Seitenverhältnis.
Zulässige Werte:1:1, 16:9, 9:16, 3:2, 2:3
callback_urlstring
Optional
Webhook-URL für die terminale Task-Zustellung.
duration_secondsinteger
Optional
Ausgabedauer in Sekunden.
Standard:8
Bereich: 1 - 30
modelstring
Erforderlich
Modell-Slug.
output_resolutionstring
Optional
Ausgabeauflösung.
Zulässige Werte:480p, 720p
Standard: 480p
promptstring
Erforderlich
Prompt zur Videogenerierung.
Grenzwert:5000
reference_image_urlsarray
Optional
Öffentliche Referenzbild-URLs.
grok-imagine-video-1.5-preview7 Felder
aspect_ratiostring
Optional
Ausgabe-Seitenverhältnis.
Zulässige Werte:1:1, 16:9, 9:16, 3:2, 2:3, auto
Standard: auto
callback_urlstring
Optional
Webhook-URL für die terminale Task-Zustellung.
duration_secondsinteger
Optional
Ausgabedauer in Sekunden.
Standard:8
Bereich: 1 - 15
modelstring
Erforderlich
Modell-Slug.
output_resolutionstring
Optional
Ausgabeauflösung.
Zulässige Werte:480p, 720p, 1080p
Standard: 480p
promptstring
Erforderlich
Prompt zur Videogenerierung.
Bereich:1 - 4096
reference_image_urlsarray
Optional
Öffentliche Referenzbild-URLs; 1080p akzeptiert höchstens ein Bild.
Elementlimit:7
Bedingte Regeln
Diese Anforderungen gelten, wenn alle aufgeführten Bedingungen zutreffen.
-
Wenn
model = grok-imagine-text-to-video- Erforderlich
- Nicht akzeptiert
reference_image_urls
-
Wenn
model = grok-imagine-video-1.5-fast- Erforderlich
- Nicht akzeptiert
motion_style,enable_safety_checker
-
Wenn
model = grok-imagine-video-1.5-preview- Erforderlich
- Nicht akzeptiert
motion_style,enable_safety_checker
04
HTTP 202Annahme erstellen
POST /api/v1/grok_imagine/text_to_video
Antwort-Schema
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"type": "string"
},
"status": {
"enum": [
"processing"
],
"type": "string"
},
"task_replayed": {
"type": "boolean"
}
},
"required": [
"id",
"status",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}Antwortbeispiel
JSON
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "processing"
}05
HTTP 200Abfrage wird verarbeitet
GET /api/v1/grok_imagine/text_to_video/:id
Antwort-Schema
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"type": "string"
},
"status": {
"enum": [
"processing"
],
"type": "string"
}
},
"required": [
"id",
"status",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}Antwortbeispiel
JSON
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "processing"
}06
HTTP 200Abfrage abgeschlossen
GET /api/v1/grok_imagine/text_to_video/:id
Antwort-Schema
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"type": "string"
},
"status": {
"enum": [
"completed"
],
"type": "string"
},
"videos": {
"items": {
"properties": {
"url": {
"type": "string",
"x-runapi-generated-media": true
}
},
"required": [
"url"
],
"type": "object",
"unevaluatedProperties": false
},
"type": "array"
}
},
"required": [
"id",
"status",
"videos",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}Antwortbeispiel
JSON
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "completed",
"videos": [
{
"url": "https://file.runapi.ai/reference-video.mp4"
}
]
}07
HTTP 200Abfrage fehlgeschlagen
GET /api/v1/grok_imagine/text_to_video/:id
Antwort-Schema
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"error": {
"type": "string"
},
"id": {
"type": "string"
},
"status": {
"enum": [
"failed"
],
"type": "string"
}
},
"required": [
"id",
"status",
"error",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}Antwortbeispiel
JSON
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"error": "Task processing failed.",
"id": "tsk_reference_demo",
"status": "failed"
}08
HTTP 200Kunden-Callback: abgeschlossen
POST callback_url
Antwort-Schema
JSON
{
"properties": {
"id": {
"type": "string"
},
"status": {
"enum": [
"completed"
],
"type": "string"
},
"videos": {
"items": {
"properties": {
"url": {
"type": "string",
"x-runapi-generated-media": true
}
},
"required": [
"url"
],
"type": "object",
"unevaluatedProperties": false
},
"type": "array"
}
},
"required": [
"id",
"status",
"videos"
],
"type": "object",
"unevaluatedProperties": false
}Antwortbeispiel
JSON
{
"id": "tsk_reference_demo",
"status": "completed",
"videos": [
{
"url": "https://file.runapi.ai/reference-video.mp4"
}
]
}09
HTTP 200Kunden-Callback: fehlgeschlagen
POST callback_url
Antwort-Schema
JSON
{
"properties": {
"error": {
"oneOf": [
{
"type": "string"
},
{
"properties": {
"code": {
"type": "string"
},
"limit_cents": {
"type": "integer"
},
"message": {
"type": "string"
},
"reset_at": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"used_cents": {
"type": "integer"
},
"window": {
"enum": [
"1h",
"1d",
"7d",
"daily",
"weekly",
"monthly",
"lifetime"
],
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object",
"unevaluatedProperties": false
}
]
},
"id": {
"type": "string"
},
"status": {
"enum": [
"failed"
],
"type": "string"
}
},
"required": [
"id",
"status",
"error"
],
"type": "object",
"unevaluatedProperties": false
}Antwortbeispiel
JSON
{
"error": {
"code": "generation_failed",
"message": "Task processing failed."
},
"id": "tsk_reference_demo",
"status": "failed"
}10
HTTP 401Fehler
POST /api/v1/grok_imagine/text_to_video
Antwort-Schema
JSON
{
"properties": {
"error": {
"description": "Für Menschen lesbare Fehlermeldung.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Antwortbeispiel
JSON
{
"error": "Authentication required"
}11
HTTP 401Fehler
GET /api/v1/grok_imagine/text_to_video/:id
Antwort-Schema
JSON
{
"properties": {
"error": {
"description": "Für Menschen lesbare Fehlermeldung.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Antwortbeispiel
JSON
{
"error": "Authentication required"
}12
HTTP 400Fehler
POST /api/v1/grok_imagine/text_to_video
Antwort-Schema
JSON
{
"oneOf": [
{
"properties": {
"error": {
"description": "Für Menschen lesbare Fehlermeldung.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
},
{
"properties": {
"error": {
"description": "Menschenlesbare Validierungszusammenfassung.",
"type": "string"
},
"errors": {
"additionalProperties": {
"items": {
"type": "string"
},
"type": "array"
},
"description": "Validierungsmeldungen nach öffentlichem Anforderungsfeld gegliedert, mit einem Array menschenlesbarer Zeichenketten für jedes Feld.",
"type": "object"
}
},
"required": [
"error",
"errors"
],
"type": "object",
"unevaluatedProperties": false
}
]
}Antwortbeispiel
JSON
{
"error": "model must be one of: grok-imagine-text-to-video, grok-imagine-video-1.5-fast, grok-imagine-video-1.5-preview"
}13
HTTP 402Fehler
POST /api/v1/grok_imagine/text_to_video
Antwort-Schema
JSON
{
"properties": {
"error": {
"description": "Für Menschen lesbare Fehlermeldung.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Antwortbeispiel
JSON
{
"error": "Insufficient balance"
}14
HTTP 429Fehler
POST /api/v1/grok_imagine/text_to_video
Antwort-Schema
JSON
{
"properties": {
"error": {
"description": "Für Menschen lesbare Fehlermeldung.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Antwortbeispiel
JSON
{
"error": "API key credit limit exceeded"
}15
HTTP 409Fehler
POST /api/v1/grok_imagine/text_to_video
Antwort-Schema
JSON
{
"properties": {
"error": {
"description": "Für Menschen lesbare Fehlermeldung.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Antwortbeispiel
JSON
{
"error": "The request uses features that are not supported for the selected model"
}16
HTTP 429Fehler
POST /api/v1/grok_imagine/text_to_video
Antwort-Schema
JSON
{
"properties": {
"error": {
"description": "Für Menschen lesbare Fehlermeldung.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Antwortbeispiel
JSON
{
"error": "Rate limit reached. Please retry later."
}17
HTTP 503Fehler
POST /api/v1/grok_imagine/text_to_video
Antwort-Schema
JSON
{
"properties": {
"error": {
"description": "Für Menschen lesbare Fehlermeldung.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Antwortbeispiel
JSON
{
"error": "Service under maintenance, please try again later"
}18
HTTP 504Fehler
POST /api/v1/grok_imagine/text_to_video
Antwort-Schema
JSON
{
"properties": {
"error": {
"description": "Für Menschen lesbare Fehlermeldung.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Antwortbeispiel
JSON
{
"error": "The request timed out"
}19
HTTP 404Fehler
GET /api/v1/grok_imagine/text_to_video/:id
Antwort-Schema
JSON
{
"properties": {
"error": {
"description": "Für Menschen lesbare Fehlermeldung.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}Antwortbeispiel
JSON
{
"error": "Task with id 'tsk_reference_demo' not found"
}20
Generierte Code-Beispiele
Verwende cURL direkt oder installiere ein SDK für deine Programmiersprache. Jedes Beispiel übermittelt die in dieser Referenz gezeigte validierte Anfrage.
Installieren
Shell
pip install runapi-grok-imagine
PYTHON
import os
from runapi.grok_imagine import GrokImagineClient
client = GrokImagineClient(api_key=os.environ["RUNAPI_API_KEY"])
task = client.text_to_video.create(
model="grok-imagine-video-1.5-preview",
prompt="A glass greenhouse in a quiet forest."
)