openai/openai-python · error · ValueError

Expected a non-empty value for `video_id` but received {vide

Error message

Expected a non-empty value for `video_id` but received {video_id!r}

What it means

The Videos.retrieve method requires a non-empty video_id string because it is interpolated directly into the request path /videos/{video_id}. The SDK validates path parameters up front and raises ValueError before any HTTP request is made when the value is empty ("" or None). This mirrors the poll helper, which calls retrieve on each iteration until the video completes.

Source

Thrown at src/openai/resources/videos.py:239

        extra_headers: Headers | None = None,
        extra_query: Query | None = None,
        extra_body: Body | None = None,
        timeout: float | httpx2.Timeout | None | NotGiven = not_given,
    ) -> Video:
        """
        Fetch the latest metadata for a generated video.

        Args:
          extra_headers: Send extra headers

          extra_query: Add additional query parameters to the request

          extra_body: Add additional JSON properties to the request

          timeout: Override the client-level default timeout for this request, in seconds
        """
        if not video_id:
            raise ValueError(f"Expected a non-empty value for `video_id` but received {video_id!r}")
        return self._get(
            path_template("/videos/{video_id}", video_id=video_id),
            options=make_request_options(
                extra_headers=extra_headers,
                extra_query=extra_query,
                extra_body=extra_body,
                timeout=timeout,
                security={"bearer_auth": True},
            ),
            cast_to=Video,
        )

    @typing_extensions.deprecated("The Sora API is scheduled to permanently shut down on September 24, 2026.")
    def list(
        self,
        *,
        after: str | Omit = omit,
        limit: int | Omit = omit,

View on GitHub (pinned to 9917c6e28e)

Solutions

1. Check that video_id is a non-empty string before calling retrieve/poll
2. Use the id returned from client.videos.create(...) exactly as given
3. Add an assert or early return when the variable holding the id is empty

Example fix

// before
video = client.videos.poll(video_id="")

// after
created = client.videos.create(model="sora-2", prompt="...")
video = client.videos.poll(video_id=created.id)

if not isinstance(video_id, str) or not video_id.strip():
    raise ValueError("video_id must be a non-empty string")

def is_valid_video_id(v: object) -> TypeGuard[str]:
    return isinstance(v, str) and bool(v.strip())

When it happens

Trigger: Calling client.videos.retrieve(video_id=""), passing None, or calling client.videos.poll(video_id) with an empty/None id; also using a variable that was never assigned from the create() response.

Common situations: Storing the create response but reading the wrong attribute (e.g. response.id vs response.video_id), passing a dict instead of the model object, or a f-string that evaluates to empty.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• Expected a non-empty value for `user_id` but received {user_
• Expected a non-empty value for `project_id` but received {pr
• Expected a non-empty value for `character_id` but received {
• Pagination is only supported with mappings
• Expected a non-empty value for `key_id` but received {key_id

AI-assisted analysis of openai/openai-python@9917c6e28e (2026-08-28). Data as JSON: /api/errors/b0c61c1ac8c2aa24. Report an issue: GitHub.