conductor-oss/conductor · error · IOException

OpenAI Video thumbnail download failed with status %d

Error message

OpenAI Video thumbnail download failed with status %d

What it means

Thrown by OpenAIVideoApi.downloadThumbnail when GET /v1/videos/{id}/content?variant=thumbnail returns non-2xx. Message reports only the status code (no error body). This fetches the webp thumbnail associated with a completed video.

Source

Thrown at ai/src/main/java/org/conductoross/conductor/ai/providers/openai/api/OpenAIVideoApi.java:226

    }

    /**
     * Download the thumbnail for a completed video.
     *
     * @param videoId The video job ID
     * @return byte array of the thumbnail image (webp format)
     */
    public byte[] downloadThumbnail(String videoId) throws IOException {
        Request request =
                new Request.Builder()
                        .url(baseUrl + "/v1/videos/" + videoId + "/content?variant=thumbnail")
                        .header("Authorization", "Bearer " + apiKey)
                        .get()
                        .build();

        try (Response response = httpClient.newCall(request).execute()) {
            if (!response.isSuccessful()) {
                throw new IOException(
                        "OpenAI Video thumbnail download failed with status %d"
                                .formatted(response.code()));
            }
            ResponseBody body = response.body();
            if (body == null) {
                throw new IOException("OpenAI Video thumbnail download returned empty body");
            }
            return body.bytes();
        }
    }

    // -- Helpers --

    /** Safely read the response body as a string, returning empty string if body is null. */
    private String readResponseBody(Response response) throws IOException {
        ResponseBody body = response.body();
        return body != null ? body.string() : "";
    }

View on GitHub (pinned to cf7c3e4a8a)

Solutions

  1. Ensure getVideoStatus() reports 'completed' before requesting the thumbnail.
  2. On 404, treat the thumbnail as unavailable rather than retrying indefinitely.
  3. For 429, back off before retrying.
Defensive patterns

Strategy: try-catch

Validate before calling

// Only fetch thumbnail after completion
VideoStatusResponse status = videoApi.getVideoStatus(videoId);
if (!"completed".equalsIgnoreCase(status.status())) {
    throw new IllegalStateException("Video not completed: " + status.status());
}

Try / catch

try {
    byte[] thumb = videoApi.downloadThumbnail(videoId);
} catch (IOException e) {
    if (e.getMessage().contains("status 404")) {
        // thumbnail not available - degrade gracefully (skip thumbnail)
    } else {
        throw e;
    }
}

Prevention

When it happens

Trigger: Downloading a thumbnail before the video is complete (400/409), the video/thumbnail asset expired (404/410), invalid key (401), or rate limiting (429). Some completed jobs may not have a thumbnail.

Common situations: Calling downloadThumbnail before status is completed, thumbnail not generated for the job (404), or asset TTL elapsed.

Related errors

AI-assisted analysis of conductor-oss/conductor@cf7c3e4a8a (2026-08-14). Data as JSON: /api/errors/4740b79949aec38d. Report an issue: GitHub.