Przejdź do treści
Dokumentacja API
Dokumentacja API

Grok Imagine Zamiana tekstu na wideo

Użyj punktu końcowego text to video, aby utworzyć asynchroniczne zadanie.

Zobacz Markdown
01

Omówienie

Użyj punktu końcowego text to video z obsługiwanym modelem. Użyj zwróconego identyfikatora zadania, aby pobrać jego stan, lub podaj callback_url dla dostarczeń udokumentowanych poniżej.

Szybki start

  1. Utwórz klucz API i ustaw go jako RUNAPI_API_KEY.
  2. Wybierz obsługiwany model i wyślij żądanie POST, którego treść odpowiada schematowi tego modelu.
  3. Zapisz zwrócony identyfikator zadania, a następnie odpytuj do momentu osiągnięcia stanu końcowego lub obsłuż wywołania zwrotne opisane poniżej.

Punkt końcowy

POST /api/v1/grok_imagine/text_to_video
Bazowy URL
https://runapi.ai
Wersja API
v1
Uwierzytelnianie
Authorization: Bearer YOUR_API_TOKEN
02

Obsługiwane modele

Otwórz stronę modelu, aby zapoznać się z aktualnymi cenami, limitami żądań i szczegółami dotyczącymi użytku komercyjnego.

03

Schemat żądania

Treść JSON

Pola i dozwolone wartości zależą od wybranego modelu. Jeśli zostanie podany, callback_url będzie odbierać dostarczenia zadań (Task) opisane poniżej.

grok-imagine-text-to-video8 pola
aspect_ratiostring
Opcjonalne

Współczynnik proporcji danych wyjściowych.

Dozwolone wartości: 2:3, 3:2, 1:1, 16:9, 9:16
callback_urlstring
Opcjonalne

URL webhooka dla końcowego dostarczenia zadania.

duration_secondsinteger
Opcjonalne

Czas trwania danych wyjściowych w sekundach.

Zakres: 6 - 30
enable_safety_checkerboolean
Opcjonalne

Włącz sprawdzanie bezpieczeństwa treści.

modelstring
Wymagane

Identyfikator modelu.

motion_stylestring
Opcjonalne

Styl ruchu w wideo.

Dozwolone wartości: fun, normal, spicy
output_resolutionstring
Opcjonalne

Rozdzielczość wyjściowa.

Dozwolone wartości: 480p, 720p Domyślna wartość: 480p
promptstring
Wymagane

Prompt generowania wideo.

Zakres: 5000
grok-imagine-video-1.5-fast7 pola
aspect_ratiostring
Opcjonalne

Współczynnik proporcji danych wyjściowych.

Dozwolone wartości: 1:1, 16:9, 9:16, 3:2, 2:3
callback_urlstring
Opcjonalne

URL webhooka dla końcowego dostarczenia zadania.

duration_secondsinteger
Opcjonalne

Czas trwania danych wyjściowych w sekundach.

Domyślna wartość: 8 Zakres: 1 - 30
modelstring
Wymagane

Identyfikator modelu.

output_resolutionstring
Opcjonalne

Rozdzielczość wyjściowa.

Dozwolone wartości: 480p, 720p Domyślna wartość: 480p
promptstring
Wymagane

Prompt generowania wideo.

Zakres: 5000
reference_image_urlsarray
Opcjonalne

Publiczne adresy URL referencyjnych obrazów.

grok-imagine-video-1.5-preview7 pola
aspect_ratiostring
Opcjonalne

Współczynnik proporcji danych wyjściowych.

Dozwolone wartości: 1:1, 16:9, 9:16, 3:2, 2:3, auto Domyślna wartość: auto
callback_urlstring
Opcjonalne

URL webhooka dla końcowego dostarczenia zadania.

duration_secondsinteger
Opcjonalne

Czas trwania danych wyjściowych w sekundach.

Domyślna wartość: 8 Zakres: 1 - 15
modelstring
Wymagane

Identyfikator modelu.

output_resolutionstring
Opcjonalne

Rozdzielczość wyjściowa.

Dozwolone wartości: 480p, 720p, 1080p Domyślna wartość: 480p
promptstring
Wymagane

Prompt generowania wideo.

Zakres: 1 - 4096
reference_image_urlsarray
Opcjonalne

Publiczne adresy URL referencyjnych obrazów; rozdzielczość 1080p akceptuje co najwyżej jeden obraz.

Limit elementów: 7

Reguły warunkowe

Te wymagania obowiązują, gdy spełnione są wszystkie wymienione warunki.

  1. Kiedy model = grok-imagine-text-to-video
    Wymagane
    Nie jest akceptowane
    reference_image_urls
  2. Kiedy model = grok-imagine-video-1.5-fast
    Wymagane
    Nie jest akceptowane
    motion_style, enable_safety_checker
  3. Kiedy model = grok-imagine-video-1.5-preview
    Wymagane
    Nie jest akceptowane
    motion_style, enable_safety_checker
04

Tworzenie akceptacji

HTTP 202

POST /api/v1/grok_imagine/text_to_video

Schemat odpowiedzi
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
}

Przykład odpowiedzi

JSON 
{
  "billing": {
    "refund": null,
    "reservation": null,
    "settlement": null
  },
  "id": "tsk_reference_demo",
  "status": "processing"
}
05

Odpytywanie w toku

HTTP 200

GET /api/v1/grok_imagine/text_to_video/:id

Schemat odpowiedzi
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
}

Przykład odpowiedzi

JSON 
{
  "billing": {
    "refund": null,
    "reservation": null,
    "settlement": null
  },
  "id": "tsk_reference_demo",
  "status": "processing"
}
06

Odpytywanie zakończone

HTTP 200

GET /api/v1/grok_imagine/text_to_video/:id

Schemat odpowiedzi
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
}

Przykład odpowiedzi

JSON 
{
  "billing": {
    "refund": null,
    "reservation": null,
    "settlement": null
  },
  "id": "tsk_reference_demo",
  "status": "completed",
  "videos": [
    {
      "url": "https://file.runapi.ai/reference-video.mp4"
    }
  ]
}
07

Odpytywanie nie powiodło się

HTTP 200

GET /api/v1/grok_imagine/text_to_video/:id

Schemat odpowiedzi
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
}

Przykład odpowiedzi

JSON 
{
  "billing": {
    "refund": null,
    "reservation": null,
    "settlement": null
  },
  "error": "Task processing failed.",
  "id": "tsk_reference_demo",
  "status": "failed"
}
08

Wywołanie zwrotne klienta: ukończono

HTTP 200

POST callback_url

Schemat odpowiedzi
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
}

Przykład odpowiedzi

JSON 
{
  "id": "tsk_reference_demo",
  "status": "completed",
  "videos": [
    {
      "url": "https://file.runapi.ai/reference-video.mp4"
    }
  ]
}
09

Wywołanie zwrotne klienta: niepowodzenie

HTTP 200

POST callback_url

Schemat odpowiedzi
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
}

Przykład odpowiedzi

JSON 
{
  "error": {
    "code": "generation_failed",
    "message": "Task processing failed."
  },
  "id": "tsk_reference_demo",
  "status": "failed"
}
10

Błędy

HTTP 401

POST /api/v1/grok_imagine/text_to_video

Schemat odpowiedzi
JSON 
{
  "properties": {
    "error": {
      "description": "Czytelny dla człowieka komunikat o błędzie.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Przykład odpowiedzi

JSON 
{
  "error": "Authentication required"
}
11

Błędy

HTTP 401

GET /api/v1/grok_imagine/text_to_video/:id

Schemat odpowiedzi
JSON 
{
  "properties": {
    "error": {
      "description": "Czytelny dla człowieka komunikat o błędzie.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Przykład odpowiedzi

JSON 
{
  "error": "Authentication required"
}
12

Błędy

HTTP 400

POST /api/v1/grok_imagine/text_to_video

Schemat odpowiedzi
JSON 
{
  "oneOf": [
    {
      "properties": {
        "error": {
          "description": "Czytelny dla człowieka komunikat o błędzie.",
          "type": "string"
        }
      },
      "required": [
        "error"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    {
      "properties": {
        "error": {
          "description": "Czytelne dla człowieka podsumowanie walidacji.",
          "type": "string"
        },
        "errors": {
          "additionalProperties": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "description": "Komunikaty walidacyjne identyfikowane przez publiczne pole żądania, z tablicą czytelnych dla człowieka ciągów znaków dla każdego pola.",
          "type": "object"
        }
      },
      "required": [
        "error",
        "errors"
      ],
      "type": "object",
      "unevaluatedProperties": false
    }
  ]
}

Przykład odpowiedzi

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

Błędy

HTTP 402

POST /api/v1/grok_imagine/text_to_video

Schemat odpowiedzi
JSON 
{
  "properties": {
    "error": {
      "description": "Czytelny dla człowieka komunikat o błędzie.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Przykład odpowiedzi

JSON 
{
  "error": "Insufficient balance"
}
14

Błędy

HTTP 429

POST /api/v1/grok_imagine/text_to_video

Schemat odpowiedzi
JSON 
{
  "properties": {
    "error": {
      "description": "Czytelny dla człowieka komunikat o błędzie.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Przykład odpowiedzi

JSON 
{
  "error": "API key credit limit exceeded"
}
15

Błędy

HTTP 409

POST /api/v1/grok_imagine/text_to_video

Schemat odpowiedzi
JSON 
{
  "properties": {
    "error": {
      "description": "Czytelny dla człowieka komunikat o błędzie.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Przykład odpowiedzi

JSON 
{
  "error": "The request uses features that are not supported for the selected model"
}
16

Błędy

HTTP 429

POST /api/v1/grok_imagine/text_to_video

Schemat odpowiedzi
JSON 
{
  "properties": {
    "error": {
      "description": "Czytelny dla człowieka komunikat o błędzie.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Przykład odpowiedzi

JSON 
{
  "error": "Rate limit reached. Please retry later."
}
17

Błędy

HTTP 503

POST /api/v1/grok_imagine/text_to_video

Schemat odpowiedzi
JSON 
{
  "properties": {
    "error": {
      "description": "Czytelny dla człowieka komunikat o błędzie.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Przykład odpowiedzi

JSON 
{
  "error": "Service under maintenance, please try again later"
}
18

Błędy

HTTP 504

POST /api/v1/grok_imagine/text_to_video

Schemat odpowiedzi
JSON 
{
  "properties": {
    "error": {
      "description": "Czytelny dla człowieka komunikat o błędzie.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Przykład odpowiedzi

JSON 
{
  "error": "The request timed out"
}
19

Błędy

HTTP 404

GET /api/v1/grok_imagine/text_to_video/:id

Schemat odpowiedzi
JSON 
{
  "properties": {
    "error": {
      "description": "Czytelny dla człowieka komunikat o błędzie.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Przykład odpowiedzi

JSON 
{
  "error": "Task with id 'tsk_reference_demo' not found"
}
20

Wygenerowane przykłady kodu

Używaj bezpośrednio cURL lub zainstaluj SDK dla swojego języka. Każdy przykład przesyła zwalidowane żądanie pokazane w tej dokumentacji.

Instalacja

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."
)