From Single Requests to a Reusable Application

The previous lessons sent one image and one question in isolated scripts. A real application needs more structure: a reusable function that accepts any image and any question, sensible error handling when something goes wrong, and — ideally — the ability to ask multiple follow-up questions about the same image without re-uploading it every time. This lesson builds that application step by step.

Step 1: A Reusable Core Function

import base64
import os
from openai import OpenAI

client = OpenAI()


def encode_image(path: str) -> str:
    with open(path, "rb") as f:
        return base64.b64encode(f.read()).decode("utf-8")


def guess_mime_type(path: str) -> str:
    extension = os.path.splitext(path)[1].lower()
    mime_map = {
        ".jpg": "image/jpeg",
        ".jpeg": "image/jpeg",
        ".png": "image/png",
        ".webp": "image/webp",
        ".gif": "image/gif",
    }
    if extension not in mime_map:
        raise ValueError(f"Unsupported image extension: {extension}")
    return mime_map[extension]


def ask_about_image(image_path: str, question: str) -> str:
    mime_type = guess_mime_type(image_path)
    encoded = encode_image(image_path)

    response = client.responses.create(
        model="gpt-5.6-terra",
        input=[
            {
                "role": "user",
                "content": [
                    {"type": "input_text", "text": question},
                    {
                        "type": "input_image",
                        "image_url": f"data:{mime_type};base64,{encoded}",
                        "detail": "high",
                    },
                ],
            }
        ],
    )
    return response.output_text

This splits responsibility across three small functions rather than one large one:

• encode_image handles the pure byte-to-base64 conversion, as in earlier lessons.
• guess_mime_type inspects the file extension and raises a clear ValueError for unsupported formats, rather than silently sending an incorrect or missing MIME type and getting a confusing failure later from the API.
• ask_about_image composes the two helpers into the actual request, keeping the request-building logic focused and easy to read.

Separating these concerns makes the code easier to test and easier to extend — for example, if you later want to support fetching images from a URL as well as from disk, you only need to add a new encoding path, not rewrite the whole function.

Step 2: Validating Input Before Spending an API Call

A production application should not send a request to the API only to discover the file doesn't exist or the question is empty. Catch these problems early:

def ask_about_image_safe(image_path: str, question: str) -> str:
    if not question or not question.strip():
        raise ValueError("Question must not be empty.")
    if not os.path.isfile(image_path):
        raise FileNotFoundError(f"No such image file: {image_path}")

    return ask_about_image(image_path, question)

Why check question.strip() rather than just question? Because a string containing only whitespace is truthy in Python (bool(" ") is True), so a bare if not question check would let a meaningless whitespace-only question through undetected. Stripping first ensures an empty-looking question is actually treated as empty. Checking os.path.isfile before attempting to open the file lets you raise a clear, specific error (FileNotFoundError with the actual path) rather than letting a low-level open() failure surface with a less helpful message deep inside encode_image.

Step 3: A Simple Interactive Loop

With the core function in place, wrapping it in an interactive command-line loop is straightforward:

def run_interactive_session(image_path: str) -> None:
    print(f"Ask questions about {image_path}. Type 'quit' to exit.")
    while True:
        question = input("> ").strip()
        if question.lower() in ("quit", "exit"):
            break
        if not question:
            continue
        try:
            answer = ask_about_image_safe(image_path, question)
            print(answer)
        except Exception as error:
            print(f"Could not process the request: {error}")


if __name__ == "__main__":
    run_interactive_session("photos/kitchen_layout.jpg")

Each part of this loop earns its place:

• The while True loop keeps asking for input until the user explicitly quits, which is the expected behavior for an interactive Q&A tool over a single fixed image.
• Checking for "quit" or "exit" (case-insensitively, via .lower()) gives the user a predictable way to end the session.
• The empty-question check (if not question: continue) silently skips blank input rather than sending a wasted, invalid request.
• The try/except around the actual API call ensures that a single failed request — a network hiccup, an invalid file, a transient API error — doesn't crash the entire session. The user sees a clear message and can simply try again.

Note that catching a bare Exception here is a deliberate, narrow choice appropriate for a top-level interactive loop whose job is to stay alive and keep prompting the user; it would be too broad inside library code that other functions call, where callers need to know specifically what went wrong.

Step 4: Testing the Logic Without Calling the Real API

You should not call the live API inside a test — it costs money, requires network access, and makes tests non-deterministic. Instead, test the validation logic directly, and use a fake stand-in for anything that would otherwise reach the network:

def fake_ask_about_image(image_path: str, question: str) -> str:
    return f"FAKE ANSWER for '{question}' about {image_path}"


def test_empty_question_is_rejected():
    try:
        ask_about_image_safe("photos/kitchen_layout.jpg", "   ")
        assert False, "Expected a ValueError for an empty question"
    except ValueError:
        pass
    print("PASS: empty question is rejected")


def test_missing_file_is_rejected():
    try:
        ask_about_image_safe("photos/does_not_exist.jpg", "What is this?")
        assert False, "Expected a FileNotFoundError for a missing file"
    except FileNotFoundError:
        pass
    print("PASS: missing file is rejected")


def test_guess_mime_type_rejects_unknown_extension():
    try:
        guess_mime_type("document.txt")
        assert False, "Expected a ValueError for an unsupported extension"
    except ValueError:
        pass
    print("PASS: unsupported extension is rejected")


if __name__ == "__main__":
    test_empty_question_is_rejected()
    test_missing_file_is_rejected()
    test_guess_mime_type_rejects_unknown_extension()

These tests exercise ask_about_image_safe and guess_mime_type directly, both of which fail fast on bad input before ever reaching the network call inside ask_about_image. Because the validation happens first, these tests never actually trigger an API request — there's nothing to fake at the network layer for these particular cases. When you do need to test code that depends on the API's response (for example, code that parses response.output_text into a specific shape), the right approach is dependency injection: pass in a fake client or a fake function like fake_ask_about_image above instead of the real one, so your test exercises your logic without ever making a real network call.

Common Mistakes

Sending a request before validating that the file exists, which produces a confusing low-level file error deep inside the encoding step instead of a clear, actionable message at the point where the mistake actually originated.

Catching exceptions too broadly inside reusable library functions, which hides the specific cause of a failure from the calling code. Broad except Exception blocks belong at the outermost layer of an application (like the interactive loop above), not buried inside functions other code depends on.

Writing tests that call the real API, which makes the test suite slow, costly, and flaky due to network variability. Always isolate the parts of your logic that don't require the network and test those directly, using fakes for anything that would otherwise reach out to the API.

Best Practices

Separate encoding, validation, and request-building into distinct functions, so each piece can be tested, reused, and modified independently.

Fail fast with specific exception types (ValueError, FileNotFoundError) rather than generic ones, so calling code can distinguish between different failure causes and react appropriately.

Keep the interactive or user-facing loop resilient to individual request failures, using a narrow, well-placed try/except so one bad question or transient error doesn't end the entire session.