> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumenfall.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get video

> Check the status of a video generation request

Retrieve the current status and output of a video generation request. Use this endpoint to poll for completion after submitting a video with [`POST /v1/videos`](/api-reference/videos/generate).

## Path parameters

<ParamField path="id" type="string" required>
  The ID of the video to retrieve (returned from the generate endpoint).
</ParamField>

## Response

<ResponseField name="id" type="string">
  Unique identifier for the video.
</ResponseField>

<ResponseField name="object" type="string">
  Always `"video"`.
</ResponseField>

<ResponseField name="created_at" type="integer">
  Unix timestamp of when the video was created.
</ResponseField>

<ResponseField name="completed_at" type="integer">
  Unix timestamp of when the video finished generating. `null` until completed.
</ResponseField>

<ResponseField name="expires_at" type="integer">
  Unix timestamp of when the video output URL will expire. `null` until completed.
</ResponseField>

<ResponseField name="status" type="string">
  The generation status. One of `queued`, `in_progress`, `completed`, or `failed`.
</ResponseField>

<ResponseField name="model" type="string">
  The model used for generation.
</ResponseField>

<ResponseField name="prompt" type="string">
  The prompt used to generate the video.
</ResponseField>

<ResponseField name="seconds" type="string">
  The video duration.
</ResponseField>

<ResponseField name="size" type="string">
  Output dimensions as `"WIDTHxHEIGHT"` (e.g., `"1920x1080"`) or aspect ratio (e.g., `"16:9"`).
</ResponseField>

<ResponseField name="output" type="object">
  The generated video output. Only present when status is `completed`.

  <Expandable title="Output object">
    <ResponseField name="url" type="string">
      URL of the generated video file. This URL expires at `expires_at`.
    </ResponseField>

    <ResponseField name="content_type" type="string">
      MIME type of the video (e.g., `video/mp4`).
    </ResponseField>

    <ResponseField name="size_bytes" type="integer">
      Size of the video file in bytes.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="error" type="object">
  Error details. Only present when status is `failed`.

  <Expandable title="Error object">
    <ResponseField name="code" type="string">
      Error code.
    </ResponseField>

    <ResponseField name="message" type="string">
      Human-readable error message.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="metadata" type="object">
  Metadata about the request execution, including cost. See [Billing](/billing#effective-cost-on-responses).

  <Expandable title="Metadata object">
    <ResponseField name="provider_name" type="string">
      Provider display name (e.g., `"Google Vertex AI"`).
    </ResponseField>

    <ResponseField name="provider" type="string">
      Provider slug (e.g., `"replicate"`).
    </ResponseField>

    <ResponseField name="upstream_id" type="string">
      The provider's job ID, useful for reconciliation.
    </ResponseField>

    <ResponseField name="model" type="string">
      The model string sent in the request.
    </ResponseField>

    <ResponseField name="executed_model" type="string">
      The model that was actually executed, as `"{provider_slug}/{provider_model}"`.
    </ResponseField>

    <ResponseField name="cost" type="number">
      Final effective cost. Only present when the job is `completed`.
    </ResponseField>

    <ResponseField name="cost_estimate" type="number">
      Estimated cost. Present while the job is `queued` or `in_progress`.
    </ResponseField>

    <ResponseField name="cost_currency" type="string">
      Currency of the cost (e.g., `"USD"`).
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl https://api.lumenfall.ai/openai/v1/videos/video_abc123 \
    -H "Authorization: Bearer $LUMENFALL_API_KEY"
  ```

  ```python Python theme={null}
  import time
  from openai import OpenAI

  client = OpenAI(
      api_key="your-lumenfall-api-key",
      base_url="https://api.lumenfall.ai/openai/v1"
  )

  # Poll until the video is ready
  video_id = "video_abc123"
  while True:
      video = client.videos.retrieve(video_id)

      if video.status == "completed":
          print(video.output.url)
          break
      elif video.status == "failed":
          print(f"Error: {video.error.message}")
          break

      time.sleep(5)
  ```

  ```typescript JavaScript / TypeScript theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
    apiKey: "your-lumenfall-api-key",
    baseURL: "https://api.lumenfall.ai/openai/v1",
  });

  // Poll until the video is ready
  const videoId = "video_abc123";
  while (true) {
    const video = await client.videos.retrieve(videoId);

    if (video.status === "completed") {
      console.log(video.output.url);
      break;
    } else if (video.status === "failed") {
      console.error(`Error: ${video.error.message}`);
      break;
    }

    await new Promise((r) => setTimeout(r, 5000));
  }
  ```
</RequestExample>

<ResponseExample>
  ```json In progress theme={null}
  {
    "id": "video_abc123",
    "object": "video",
    "created_at": 1702345678,
    "completed_at": null,
    "expires_at": null,
    "status": "in_progress",
    "model": "sora-2",
    "prompt": "A capybara lounging in a hot spring, steam rising gently, slow camera pan",
    "seconds": "10",
    "size": "1920x1080",
    "output": null,
    "error": null,
    "metadata": {
      "model": "sora-2",
      "executed_model": "openai/sora-2",
      "provider": "openai",
      "provider_name": "OpenAI",
      "cost_estimate": 0.21,
      "cost_currency": "USD"
    }
  }
  ```

  ```json Completed theme={null}
  {
    "id": "video_abc123",
    "object": "video",
    "created_at": 1702345678,
    "completed_at": 1702345720,
    "expires_at": 1702432120,
    "status": "completed",
    "model": "sora-2",
    "prompt": "A capybara lounging in a hot spring, steam rising gently, slow camera pan",
    "seconds": "10",
    "size": "1920x1080",
    "output": {
      "url": "https://media.lumenfall.ai/video_abc123.mp4",
      "content_type": "video/mp4",
      "size_bytes": 15728640
    },
    "error": null,
    "metadata": {
      "model": "sora-2",
      "executed_model": "openai/sora-2",
      "provider": "openai",
      "provider_name": "OpenAI",
      "cost": 0.21,
      "cost_currency": "USD"
    }
  }
  ```
</ResponseExample>