Responses API image input model mismatch with ImageInputContent

[Edvinas-Mas]

Issue description

I am migrating from the Assistants API to the Responses API.

According to the official OpenAI API specification (see screenshot below), the Responses API supports image input in two ways:

1. By providing a file_id reference.
2. By providing an image_url.

These fields are alternatives — only one of them should be required for a valid request.

However, in the Java client (Input -> ImageInputContent), the image_url field is marked as @Required. This makes it impossible to send an image by file_id alone, because validation fails before the request is sent.

As a result, the following workflow is blocked:

• I upload an image file.
• I receive a file_id.
• I try to reference that file_id in the image input for the Responses API request.
• The client rejects the request because image_url is missing, even though file_id is provided.

Screenshot from the official OpenAI spec:

---

Expected behavior

• The Java client should allow constructing a valid ImageInputContent when either file_id or image_url is provided, matching the OpenAI API spec.

Actual behavior

• The Java client marks image_url as @Required, causing validation to fail if it is omitted, even when file_id is present.

---

Minimal reproducible example

  List<Object> inputs  =new ArrayList<>();
  TextInputContent textInput = TextInputContent.of("What is in this image?");
  ImageInputContent imageInput = ImageInputContent.builder()
          .fileId(entity.getRequest().getEntityId())
          .detail(ImageDetail.AUTO)
          //  .imageUrl(entity.getRequest().getMediaUrl().getFirst()) <-- omitted intentionally
          .build();
  InputMessage inputMsg = InputMessage.of(List.of(textInput, imageInput), Input.MessageRole.USER);
  inputs.add(inputMsg);

  ResponseRequest request = ResponseRequest.builder()
          .model("gpt-4o")
          .input(inputs)
          .build();

  openAI.responses().create(request).join();

Result:

Validation error — image_url is required.

Expected:

The request should be sent successfully, as file_id is provided.

[sashirestela]

@Edvinas-Mas Thank you for using simpe-openai. It's very important that you identify these differences between the implementation and the specification, as OpenAI unfortunately doesn't communicate these small changes effectively, and I don't have a better way to detect them.

[amavashev]

Any updates on when this problem will be fixed? Thanks.