MediaResponse是否支持mediaObject数组？文档与实际报错的矛盾咨询

Great question—this is definitely one of those API design quirks that can leave you scratching your head at first, especially when you hit that frustrating error message:

MalformedResponse at expected_inputs[0].input_prompt.rich_initial_prompt.items 1 .media_response: Only 1 media_object is allowed. First media_object will be used while rest will be filtered.

Here are the most practical reasons behind this seemingly contradictory design choice:

• Forward compatibility
  The array structure is a future-proofing move. API designers often build in support for expanded functionality upfront so they can enable multiple media objects later without breaking existing integrations. When that feature launches, you won’t have to refactor how you pass media data—you’ll already be using the correct structure.

• Consistency across the API suite
  If other related endpoints in the same ecosystem support multiple media objects, using an array here keeps the overall design consistent. This reduces cognitive load for developers: you don’t have to memorize whether each endpoint expects a single object or an array—you can follow the same pattern across the board.

• Simplified backend processing
  Handling arrays is often cleaner on the backend than mixing single objects and arrays. Even if only the first item is used, the backend can rely on uniform array-processing logic (like grabbing the first element) instead of writing conditional checks to handle both object and array inputs. This cuts down on bugs and makes the codebase easier to maintain.

• Edge case flexibility
  While the current error says extra objects get filtered, there might be specific contexts (like certain device types, interaction modes, or future feature flags) where multiple media objects could be supported. The array structure leaves the door open for these edge cases without a full API rewrite.

At the end of the day, it’s a classic example of designing APIs for what might come, not just what’s currently available.

内容的提问来源于stack exchange，提问作者Yue Zhuo