Responses API: sending a client-authored assistant turn requires either a fake message id or a `# type: ignore`

[adubovik]

Confirm this is an issue with the Python library and not an underlying OpenAI API

• This is an issue with the Python library

Describe the bug

Conversation histories don't always come back from the API. Assistant turns can be replayed
from storage, edited before being sent again, produced by other code, or carried over from
somewhere else. A turn like that has no OpenAI message id, because no API call ever produced
one. I'd like to pass it in input and have the request types support that.

The only version the types accept makes me fill in an id and a status I don't have:

conversation: ResponseInputParam = [
    {"role": "user", "content": [{"type": "input_text", "text": "2+3=?"}]},
    {
        "type": "message",
        "id": "msg_fake_msg_id",      # <-- made up
        "status": "completed",        # <-- made up
        "role": "assistant",
        "content": [
            {"type": "output_text", "text": "5", "annotations": []},
            {"type": "output_text", "text": "something else?", "annotations": []},
        ],
    },
    {"role": "user", "content": [{"type": "input_text", "text": "what's the square of the result?"}]},
]

The id is the part that worries me, since ids plausibly take part in prompt caching. To be
safe about it I'd have to invent a scheme that derives the same synthetic id for the same
conversation prefix every time and keep that stable across versions. That's real work whose
only purpose is keeping the type checker quiet.

There are two other ways to write the same turn. Neither needs an id, and they fail in
opposite directions.

The first one just leaves id and status out, and the API is fine with it: the request goes
through and comes back with a normal answer (checked against the live endpoint, openai 2.48.0).
Only the types object, which suggests those two fields are the SDK's requirement rather than
the service's:

    {
        "type": "message",
        "role": "assistant",
        "content": [
            {"type": "output_text", "text": "5", "annotations": []},  # type: ignore
            {"type": "output_text", "text": "something else?", "annotations": []},  # type: ignore
        ],
    },

Writing # type: ignore (or cast()) to send a payload the API accepts happily defeats the
point of having typed requests in the first place.

The second one type-checks with nothing suppressed, then fails on the server:

    {
        "role": "assistant",
        "content": [
            {"type": "input_text", "text": "5"},
            {"type": "input_text", "text": "something else?"},
        ],
    },

{"error": {"message": "Invalid value: 'input_text'. Supported values are: 'output_text' and 'refusal'.",
           "type": "invalid_request_error", "param": "input[1].content[0]", "code": "invalid_value"}}

So out of the three, the one that both type-checks and works is the one with made-up values in
it.

Expected behavior

Some way to express a client-authored assistant turn that type-checks and doesn't require
inventing field values.

Related issues

The id requirement also came up in #2501, and #3015 proposes relaxing it, though status is
required as well so the workarounds above would still be needed. #2323 looks adjacent.

To Reproduce

Pass each of the three snippets above to client.responses.create(model=..., input=conversation)
with a type checker enabled. In order: the first needs the made-up id and status, the second
needs # type: ignore, the third type-checks and then returns the 400 above.

Code snippets

.env:

OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-5

app.py:

import os

from dotenv import load_dotenv
from openai import OpenAI
from openai.types.responses import ResponseInputParam

load_dotenv()

client = OpenAI()


def create_conversation(option: int) -> ResponseInputParam:
    if option == 1:
        return [
            {
                "role": "user",
                "content": [{"type": "input_text", "text": "2+3=?"}],
            },
            {
                "type": "message",
                "id": "msg_fake_msg_id",
                "status": "completed",
                "role": "assistant",
                "content": [
                    {"type": "output_text", "text": "5", "annotations": []},
                    {
                        "type": "output_text",
                        "text": "something else?",
                        "annotations": [],
                    },
                ],
            },
            {
                "role": "user",
                "content": [
                    {"type": "input_text", "text": "what's the square of the result?"}
                ],
            },
        ]

    if option == 2:
        return [
            {
                "role": "user",
                "content": [{"type": "input_text", "text": "2+3=?"}],
            },
            {
                "type": "message",
                "role": "assistant",
                "content": [
                    {"type": "output_text", "text": "5", "annotations": []},  # type: ignore
                    {"type": "output_text", "text": "something else?", "annotations": []},  # type: ignore
                ],
            },
            {
                "role": "user",
                "content": [
                    {"type": "input_text", "text": "what's the square of the result?"}
                ],
            },
        ]

    return [
        {
            "role": "user",
            "content": [{"type": "input_text", "text": "2+3=?"}],
        },
        {
            "role": "assistant",
            "content": [
                {"type": "input_text", "text": "5"},
                {"type": "input_text", "text": "something else?"},
            ],
        },
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "what's the square of the result?"}
            ],
        },
    ]


for i in [1, 2, 3]:
    response = client.responses.create(
        model=os.environ["OPENAI_MODEL"],
        input=create_conversation(i),
    )
    print(response.output_text)

OS

macOS 14.6

Python version

3.11.13

Library version

openai 2.48.0 (checked with pyright 1.1.411)

[Aditya-myst]

There's a fourth formulation that type-checks with no suppressions and no invented
values — passing content as a plain string, which routes to EasyInputMessageParam
rather than ResponseOutputMessageParam:

Python

conversation: ResponseInputParam = [
{"role": "user", "content": [{"type": "input_text", "text": "2+3=?"}]},
{"role": "assistant", "content": "5"},
{"role": "user", "content": [{"type": "input_text", "text": "what's the square of the result?"}]},
]
EasyInputMessageParam.content is typed Union[str, ResponseInputMessageContentListParam]
and its role includes "assistant", so no id or status is needed. Verified clean
under pyright 1.1.411 / openai 2.49.0.

This doesn't close the issue — the string form can't carry annotations or multiple
output_text parts within one message object — but it does avoid the synthetic-id
problem for the common text-only replay case, which may be useful in the meantime.

On the underlying cause: the Required[...] markers come from the OutputMessage
schema in openai-openapi, which lists id, type, role, content, status under
required. Since this SDK is Stainless-generated from that spec, a patch to
response_output_message_param.py would be reverted on the next sync — which may be why
#3015 has stayed open. Worth noting #3015 only relaxes id; status is required too, so
that PR alone wouldn't resolve this. Related spec-side report: openai/openai-openapi#475.

[adubovik]

@Aditya-myst Thanks, the spec pointer is useful. openai/openai-openapi#475 does look like where a fix has to land if the types are generated from that schema.

The string form doesn't cover my case, though. The assistant messages I'm replaying carry several text blocks inside one message, and that's the shape the API's own output messages have: content is an array of output_text/refusal parts. If a response can come back that way, sending the same message back should be expressible without a made-up ID. Right now it isn't, and that's what this issue is about.

[Aditya-myst]

Fair point the string form only handles a single text block, so it doesn't
cover replaying a message with several output_text parts. Withdrawing that as
an answer to your case.

Your framing if a response can come back that way, sending it back should be
expressible turns out to be one the spec already applies elsewhere. Comparing
the Responses output-item schemas in openai-openapi:

schema	id required	status required
OutputMessage	yes	yes
FunctionToolCall	no	no
CustomToolCall	no	—
ReasoningItem	yes	no
FileSearchToolCall / WebSearchToolCall / ComputerToolCall	yes	yes

FunctionToolCall is the interesting one. It's returned by the API and
re-sent by clients on every tool-calling round-trip the same dual role an
assistant message has. For that item the spec marks the server-assigned fields
(id, status) optional and keeps only the semantic ones (call_id, name,
arguments) required. So this type-checks with nothing invented:

{"type": "function_call", "call_id": "c1", "name": "f", "arguments": "{}"}

while the equivalent assistant message doesn't:

{"type": "message", "role": "assistant",
 "content": [{"type": "output_text", "text": "5", "annotations": []},
             {"type": "output_text", "text": "something else?", "annotations": []}]}

(pyright 1.1.411, openai 2.49.0 the message is the only error.)

That reads less like a deliberate constraint on assistant messages and more like
OutputMessage not having received the treatment its sibling already has. Not a
blanket rule either the file-search / web-search / computer calls still require
both, but those aren't items a client authors, whereas function_call and
assistant messages are.

Which suggests a narrow fix upstream: drop id and status from
OutputMessage.required, matching FunctionToolCall exactly. That also covers
the status half, which #3015 leaves open since it only relaxes id.

Happy to file that on openai-openapi with this comparison if you haven't
already -your issue, so say the word and I'll link it back here.