Zum Inhalt springen
API-Referenz
API-Referenz

Grok Imagine Bild zu Video

Verwenden Sie den Endpunkt „Bild zu Video", um einen asynchronen Task zu erstellen.

Markdown anzeigen
01

Übersicht

Verwenden Sie den Endpunkt „Bild 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

  1. Erstellen Sie einen API-Schlüssel und setzen Sie ihn als RUNAPI_API_KEY.
  2. Wählen Sie ein unterstütztes Modell und senden Sie eine POST-Anfrage, deren Body dem Schema dieses Modells entspricht.
  3. 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

POST /api/v1/grok_imagine/image_to_video
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

Anfrage-Schema

JSON-Body

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-image-to-video11 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.

indexinteger
Optional

Nullbasierter Quellbildindex; wird nur mit source_task_id verwendet.

Bereich: 0 - 5
modelstring
Erforderlich

Modell-Slug.

motion_stylestring
Optional

Bewegungsstil des Videos; „spicy" erfordert source_task_id.

Zulässige Werte: fun, normal, spicy
output_resolutionstring
Optional

Ausgabeauflösung.

Zulässige Werte: 480p, 720p Standard: 480p
promptstring
Optional

Optionaler Prompt zur Videogenerierung.

Grenzwert: 5000
source_image_urlstring
Optional

Öffentliche Quellbild-URL; geben Sie diese oder source_task_id an, aber nicht beides.

source_task_idstring
Optional

Vorherige Grok Imagine Text-to-Image-Task-ID; geben Sie diese oder source_image_url an, aber nicht beides.

grok-imagine-video-1.5-fast8 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
Optional

Optionaler Prompt zur Videogenerierung.

Grenzwert: 5000
reference_image_urlsarray
Optional

Öffentliche Referenzbild-URLs.

source_image_urlstring
Erforderlich

Öffentliche Quellbild-URL.

grok-imagine-video-1.5-preview8 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
Optional

Optionaler Prompt zur Videogenerierung.

Bereich: 1 - 4096
reference_image_urlsarray
Optional

Zusätzliche öffentliche Referenzbild-URLs; Quelle und Referenzen dürfen insgesamt sieben Bilder umfassen.

Elementlimit: 6
source_image_urlstring
Erforderlich

Öffentliche Quellbild-URL.

Bedingte Regeln

Diese Anforderungen gelten, wenn alle aufgeführten Bedingungen zutreffen.

  1. Wenn model = grok-imagine-image-to-video
    Erforderlich
    Nicht akzeptiert
    reference_image_urls
  2. Wenn model = grok-imagine-video-1.5-fast
    Erforderlich
    Nicht akzeptiert
    source_task_id, index, motion_style, enable_safety_checker
  3. Wenn model = grok-imagine-video-1.5-preview
    Erforderlich
    Nicht akzeptiert
    source_task_id, index, motion_style, enable_safety_checker
04

Annahme erstellen

HTTP 202

POST /api/v1/grok_imagine/image_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

Abfrage wird verarbeitet

HTTP 200

GET /api/v1/grok_imagine/image_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

Abfrage abgeschlossen

HTTP 200

GET /api/v1/grok_imagine/image_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

Abfrage fehlgeschlagen

HTTP 200

GET /api/v1/grok_imagine/image_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

Kunden-Callback: abgeschlossen

HTTP 200

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

Kunden-Callback: fehlgeschlagen

HTTP 200

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

Fehler

HTTP 401

POST /api/v1/grok_imagine/image_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

Fehler

HTTP 401

GET /api/v1/grok_imagine/image_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

Fehler

HTTP 400

POST /api/v1/grok_imagine/image_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-image-to-video, grok-imagine-video-1.5-fast, grok-imagine-video-1.5-preview"
}
13

Fehler

HTTP 402

POST /api/v1/grok_imagine/image_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

Fehler

HTTP 429

POST /api/v1/grok_imagine/image_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

Fehler

HTTP 409

POST /api/v1/grok_imagine/image_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

Fehler

HTTP 429

POST /api/v1/grok_imagine/image_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

Fehler

HTTP 503

POST /api/v1/grok_imagine/image_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

Fehler

HTTP 504

POST /api/v1/grok_imagine/image_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

Fehler

HTTP 404

GET /api/v1/grok_imagine/image_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.image_to_video.create(
  model="grok-imagine-video-1.5-preview",
  source_image_url="https://cdn.runapi.ai/public/samples/first-frame.jpg",
  prompt="The camera slowly moves forward."
)