> ## Documentation Index > Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt > Use this file to discover all available pages before exploring further. # Справочник по API генерации видео Grok Imagine > Справочник по API генерации видео Grok Imagine и интерактивное тестирование — текст в видео / изображение в видео, асинхронный трёхэтапный процесс, 1–15 секунд, 480p / 720p / 1080p, посекундная тарификация аналогично xAI > [!WARNING] > > **🔒 Требуется группа `GrokOfficial`, доступ предоставляется по заявке**: Grok Imagine Video не входит в группу `Default`; перед вызовом необходимо запросить доступ (включая Playground на этой странице). Без доступа или с pay-per-request token каждый вызов возвращает `503`. См. раздел [Обзор Grok Imagine Video — настройка группы](/ru/api-capabilities/grok-imagine-video/overview#group-setup). > [!NOTE] > > Интерактивный Playground справа позволяет протестировать эндпоинт напрямую. Введите ваш API-ключ в **Authorization** (формат: `Bearer sk-xxx`), выберите `model`, заполните `prompt` / `seconds` / `size` и отправьте запрос; добавьте `input_reference` для image-to-video. **Playground выполняет только шаг 1 (отправка)** — получив `id` задачи, выполняйте опрос и скачивание, как показано ниже. > [!WARNING] > > **⚠️ Три самые распространенные ошибки** > > 1. **Без `size` / `seconds` по умолчанию используются 480p и 8 секунд**, и именно они тарифицируются. > 2. **У `grok-imagine-video` нет разрешения 1080p**: `1920x1080` возвращает 400; используйте `-1.5` или `-1.5-lite` для 1080p. > 3. **Блокировки модерации тарифицируются**: заблокированная задача по-прежнему возвращает `completed`, но содержит `error.code: "moderation_blocked"` и не содержит видео. > [!WARNING] > > **Трехэтапный асинхронный процесс — эта страница описывает только шаг 1 (отправка)** > > * **Шаг 1 (эта страница)**: `POST /v1/videos` → возвращает `id` задачи + `status: "queued"` > * **Шаг 2**: опрашивайте `GET /v1/videos/{id}`, пока `status` не примет значение `"completed"` или `"failed"` > * **Шаг 3**: скачайте MP4 из `GET /v1/videos/{id}/content` > > Отправка выполняется за считанные секунды и **не** ожидает готовности видео. ## Примеры кода ### Python (генерация видео по тексту, все три шага) ```python theme={null} import os, time, requests BASE = "https://api.apiyi.com/v1" H = {"Authorization": f"Bearer {os.environ['APIYI_API_KEY']}"} # Step 1: submit task = requests.post(f"{BASE}/videos", headers=H, json={ "model": "grok-imagine-video-1.5", "prompt": "A lighthouse on the coast at dusk, slow push-in, waves lapping the rocks, seabirds calling, cinematic lighting", "seconds": "5", "size": "1280x720", # 720p landscape; the default without it is 480p }, timeout=60).json() vid = task["id"] # Step 2: poll for _ in range(75): # about 10 minutes at most time.sleep(8) job = requests.get(f"{BASE}/videos/{vid}", headers=H, timeout=60).json() if job["status"] in ("completed", "failed"): break if job["status"] != "completed" or job.get("error"): # moderation_blocked: blocked by moderation, no video, but billed raise RuntimeError(job.get("error")) # Step 3: download and store right away mp4 = requests.get(f"{BASE}/videos/{vid}/content", headers=H, timeout=300) open("out.mp4", "wb").write(mp4.content) ``` ### Python (генерация видео по изображению, входное изображение в base64) ```python theme={null} import base64, os, requests H = {"Authorization": f"Bearer {os.environ['APIYI_API_KEY']}"} img = base64.b64encode(open("first-frame.jpg", "rb").read()).decode() task = requests.post("https://api.apiyi.com/v1/videos", headers=H, json={ "model": "grok-imagine-video", "prompt": "the cat slowly turns its head and blinks", "seconds": "3", "input_reference": f"data:image/jpeg;base64,{img}", # a public image URL works too }, timeout=60).json() print(task["id"]) # then poll and download as above; the output frame follows the input image ``` ### cURL ```bash theme={null} # Step 1: submit text-to-video (1.5-lite, 2 seconds at 480p) curl -X POST "https://api.apiyi.com/v1/videos" \ -H "Authorization: Bearer sk-your-api-key" \ -H "Content-Type: application/json" \ -d '{ "model": "grok-imagine-video-1.5-lite", "prompt": "a red paper boat drifting on a calm lake, gentle ripples", "seconds": "2", "size": "854x480" }' # Image-to-video can also upload a local file with multipart curl -X POST "https://api.apiyi.com/v1/videos" \ -H "Authorization: Bearer sk-your-api-key" \ -F "model=grok-imagine-video" \ -F "prompt=the cat slowly turns its head" \ -F "seconds=2" \ -F "input_reference=@first-frame.jpg" # Step 2: check status curl "https://api.apiyi.com/v1/videos/task_xxxxxxxx" \ -H "Authorization: Bearer sk-your-api-key" # Step 3: download the video curl -o out.mp4 "https://api.apiyi.com/v1/videos/task_xxxxxxxx/content" \ -H "Authorization: Bearer sk-your-api-key" ``` ### Node.js (fetch) ```javascript theme={null} import fs from 'node:fs'; const BASE = 'https://api.apiyi.com/v1'; const H = { 'Authorization': `Bearer ${process.env.APIYI_API_KEY}`, 'Content-Type': 'application/json' }; const task = await fetch(`${BASE}/videos`, { method: 'POST', headers: H, body: JSON.stringify({ model: 'grok-imagine-video-1.5-lite', prompt: 'A serene Japanese garden with cherry blossoms drifting, koi pond, golden hour', seconds: '4', size: '720x1280' // 720p portrait }) }).then(r => r.json()); let job; for (let i = 0; i < 75; i++) { await new Promise(r => setTimeout(r, 8000)); job = await fetch(`${BASE}/videos/${task.id}`, { headers: H }).then(r => r.json()); if (['completed', 'failed'].includes(job.status)) break; } if (job.status !== 'completed' || job.error) throw new Error(JSON.stringify(job.error)); const mp4 = await fetch(`${BASE}/videos/${task.id}/content`, { headers: H }); fs.writeFileSync('out.mp4', Buffer.from(await mp4.arrayBuffer())); ``` ## Краткий справочник по параметрам | Параметр | Тип | Обязательный | По умолчанию | Примечания | | - | - | - | - | - | | `model` | string | ✅ | — | `grok-imagine-video` / `grok-imagine-video-1.5` / `grok-imagine-video-1.5-lite` | | `prompt` | string | Обязательно для text-to-video | — | Сцена, объект, действие, камера, освещение; для image-to-video описывает движение | | `seconds` | string / integer | ❌ | `8` | 1–15 секунд; при выходе за пределы возвращает 400 | | `size` | string | ❌ | 480p | `WIDTHxHEIGHT` пикселей; короткая сторона определяет разрешение, а соотношение сторон округляется до ближайшего; `480p` / `720p` / `1080p` также поддерживаются | | `resolution` / `aspect_ratio` | string | ❌ | — | Нативные поля xAI; имеют приоритет при передаче вместе с `size` | | `input_reference` | string / file | ❌ | — | Входное изображение для image-to-video: публичный URL, data URI или multipart-файл | **Цена за секунду** (как у xAI): | Модель | 480p | 720p | 1080p | Входное изображение | | - | - | - | - | - | | `grok-imagine-video` | \$0.05 | \$0.07 | Не поддерживается | \$0.002 / изображение | | `grok-imagine-video-1.5` | \$0.08 | \$0.14 | \$0.25 | \$0.01 / изображение | | `grok-imagine-video-1.5-lite` | \$0.02 | \$0.03 | \$0.14 | \$0.01 / изображение | > [!NOTE] > > Тарификация моделей синхронизирована с официальными сайтами и может изменяться вслед за ними; приведенная выше таблица носит исключительно справочный характер, а официальные данные представлены на вкладке **Тарифы на модели** в верхнем меню: [Тарифы на модели](/en/models/index). ## Примеры ответов **Отправка (шаг 1)**: ```json theme={null} { "id": "task_xxxxxxxxxxxxxxxx", "object": "video", "model": "grok-imagine-video-1.5-lite", "status": "queued", "progress": 0, "created_at": 1792320668 } ``` **Выполнено (результат опроса на шаге 2)**: ```json theme={null} { "id": "task_xxxxxxxxxxxxxxxx", "object": "video", "model": "grok-imagine-video-1.5-lite", "status": "completed", "progress": 100, "seconds": "2", "created_at": 1792320668, "completed_at": 1792320715 } ``` **Заблокировано модерацией**: `status` по-прежнему `completed`, но присутствует дополнительное поле `error`, а видео для скачивания отсутствует: ```json theme={null} { "id": "task_xxxxxxxxxxxxxxxx", "status": "completed", "error": { "code": "moderation_blocked", "message": "..." } } ``` ## Связанная документация * [Обзор Grok Imagine Video](/ru/api-capabilities/grok-imagine-video/overview) — тарификация, подача заявки на группу, параметры, FAQ * [Официальные изображения Grok Imagine](/ru/api-capabilities/grok-imagine-image-official/overview) — генерация изображений в той же группе ## OpenAPI ````yaml api-reference/grok-imagine-video-openapi-en.yaml POST /v1/videos openapi: 3.1.0 info: title: Grok Imagine Video Generation API description: > xAI Grok Imagine video official channel — an OpenAI Videos-compatible async task API for text-to-video and image-to-video, priced the same as xAI per second. - Three models: `grok-imagine-video` (480p \$0.05/s, 720p \$0.07/s), `grok-imagine-video-1.5` (\$0.08 / \$0.14 / \$0.25 per second), `grok-imagine-video-1.5-lite` (\$0.02 / \$0.03 / \$0.14 per second) - `seconds` 1–15, **default 8**; without `size` the **default is 480p** - Image-to-video: add `input_reference` (image URL or base64 data URI); each input image costs an extra \$0.002 (video) / \$0.01 (1.5 / lite) - **Async task endpoint**: this call only submits; poll `GET /v1/videos/{id}` and download from `GET /v1/videos/{id}/content` - A task blocked by moderation still reports `completed` with `error.code: moderation_blocked`, has no video, and is billed **Authentication**: add `Authorization: Bearer YOUR_API_KEY` to the request headers **API Key setup**: the Token group must include **`GrokOfficial`** (granted on application) with billing mode **Pay-as-you-go Priority** or **Pay-as-you-go**; without access, or with a pay-per-request Token, calls return 503 **Get an API Key**: create a Token in the [APIYI console](https://api.apiyi.com/token) version: 1.0.0 servers: - url: https://api.apiyi.com description: Primary endpoint security: - bearerAuth: [] paths: /v1/videos: post: tags: - Video Generation summary: Submit a video generation task (text-to-video / image-to-video) description: > Submit a Grok Imagine video generation task (async); returns the task `id` and `status: "queued"`. - Required: `model`; text-to-video also needs `prompt` - Optional: `seconds` (default 8), `size` (default 480p), `input_reference` (makes it image-to-video) - **The response has no video**; poll `GET /v1/videos/{id}` until `status: "completed"`, then download the MP4 from `GET /v1/videos/{id}/content` - Typical time: about 20–25 s for 2 s at 480p, 35–50 s for image-to-video, about 110 s for 1080p on 1.5 operationId: generateGrokImagineVideo requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/GrokImagineVideoRequest' example: model: grok-imagine-video-1.5-lite prompt: >- a red paper boat drifting on a calm lake, gentle ripples, soft morning light seconds: '2' size: 854x480 responses: '200': description: Task submitted; returns the task id and queued status content: application/json: schema: $ref: '#/components/schemas/GrokImagineVideoTask' '400': description: >- Invalid parameters (resolution not supported by the model, seconds outside 1–15, missing prompt, etc.); `message` explains '401': description: Unauthorized - invalid API Key '429': description: Rate limit hit or insufficient balance '503': description: >- Token lacks the `GrokOfficial` group, or uses pay-per-request billing security: - bearerAuth: [] components: schemas: GrokImagineVideoRequest: type: object required: - model properties: model: type: string description: > Model ID (billed per second × resolution rate): - `grok-imagine-video` — 480p \$0.05/s, 720p \$0.07/s, **no 1080p** - `grok-imagine-video-1.5` — 480p \$0.08, 720p \$0.14, 1080p \$0.25 per second - `grok-imagine-video-1.5-lite` — 480p \$0.02, 720p \$0.03, 1080p \$0.14 per second enum: - grok-imagine-video - grok-imagine-video-1.5 - grok-imagine-video-1.5-lite default: grok-imagine-video-1.5-lite prompt: type: string description: >- Prompt: scene + subject + action + camera + lighting. Required for text-to-video; for image-to-video it describes motion and camera example: >- a red paper boat drifting on a calm lake, gentle ripples, soft morning light seconds: type: string description: > Duration from 1 to 15 seconds, as a string or a number; **default 8**. Out-of-range values return 400. Cost scales with seconds — use 1–2 seconds while testing. example: '2' size: type: string description: > Output size in `WIDTHxHEIGHT` pixels: the **shorter side** sets the resolution (≥1080 is 1080p, ≥720 is 720p, otherwise 480p) and the aspect ratio snaps to the nearest supported one. You can also pass `480p` / `720p` / `1080p` directly. **Without it, the default is 480p.** - `854x480` — 480p landscape (measured 848×480) - `1280x720` / `720x1280` — 720p landscape / portrait - `1920x1080` / `1080x1920` — 1080p (1.5 / 1.5-lite only) enum: - 854x480 - 480x854 - 1280x720 - 720x1280 - 1920x1080 - 1080x1920 default: 854x480 input_reference: type: string description: > Input image for image-to-video: a public image URL or a `data:image/jpeg;base64,...` data URI. Passing it makes the job image-to-video, and the output frame follows the input image. Each input image costs an extra \$0.002 (`grok-imagine-video`) or \$0.01 (1.5 / 1.5-lite). example: https://example.com/first-frame.jpg GrokImagineVideoTask: type: object properties: id: type: string description: Task ID for polling and download example: task_xxxxxxxxxxxxxxxx object: type: string description: Always `video` example: video model: type: string example: grok-imagine-video-1.5-lite status: type: string description: > Task status: - `queued` — submitted, waiting - `in_progress` — generating - `completed` — done, download from `/v1/videos/{id}/content`; with `error.code: moderation_blocked` it was blocked and has no video - `failed` — failed enum: - queued - in_progress - completed - failed example: queued progress: type: integer description: >- Progress 0–100, coarse-grained; not suitable for a precise progress bar example: 0 seconds: type: string description: Video duration, returned once done created_at: type: integer description: Task creation Unix timestamp (seconds) completed_at: type: integer description: Task completion Unix timestamp (seconds), returned once done securitySchemes: bearerAuth: type: http scheme: bearer description: API Key from the APIYI console (Token group must include GrokOfficial) ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.