GPT-5.4 Prompting Guide: Practical Patterns for the API

A reliable GPT-5.4 prompt makes the task, source material, constraints, and expected answer explicit. In an API request, you can put high-level behavior guidance in instructions and task-specific data in input; then check the response against criteria you define. The example below uses the OpenAI Python SDK and the Responses API to extract invoice fields from supplied text without guessing when information is missing.

OpenAI’s GPT-5.4 model page identifies the model ID as gpt-5.4, lists text and image input, and says the model supports the Responses API. (developers.openai.com)

A reusable prompt pattern

Adapt this structure to your task:

You are [role relevant to the task].

Goal: [specific result to produce].

Source material: Use only the information in the input below unless I explicitly ask you to use another source.

Requirements:
- [Important constraint or rule]
- [What to include or exclude]
- If required information is missing or ambiguous, mark it as missing or ambiguous. Do not guess.

Output: Return [format and fields]. Keep [length, tone, or other limits].

Input:
[task-specific data]

A role is optional; the operational details are not. State what counts as evidence, define how to handle uncertainty, and specify an output you can inspect. In the API, OpenAI describes instructions as high-level guidance about how the model should behave, including tone, goals, and examples; keep task-specific data in the input. (developers.openai.com)

Worked example: extract invoice details from supplied text

This example extracts basic fields from text your application already has. It does not use web search, image input, or tools: the supplied invoice text is the source for the task.

Prerequisites

• An OpenAI API key, available to your application as the OPENAI_API_KEY environment variable.
• Python and the OpenAI SDK (pip install openai).
• API access to gpt-5.4.

The OpenAI quickstart documents the Python SDK setup, client.responses.create(...) pattern, and response.output_text. (developers.openai.com)

Run the request

import json
from openai import OpenAI

client = OpenAI()

invoice_text = """
Invoice number: INV-2048
Supplier: Northstar Office Supply
Invoice date: 2026-04-12
Due date: 2026-05-12
Amount due: $684.20
Payment terms: Net 30
"""

instructions = """
Extract invoice fields from the supplied text.
Use only facts stated in the text; do not calculate, infer, or fill in missing values.
If a field is absent or unclear, use null for its value and explain the issue in notes.
Return only a JSON object with these keys:
invoice_number, supplier, invoice_date, due_date, amount_due, currency,
payment_terms, notes.
Types: invoice_number, supplier, invoice_date, due_date, currency, and
payment_terms are strings or null; amount_due is a number or null; notes is
an array of strings.
Represent amount_due as a number, without a currency symbol.
"""

response = client.responses.create(
    model="gpt-5.4",
    instructions=instructions,
    input=f"Extract the invoice details from this text:\n\n{invoice_text}",
)

try:
    invoice = json.loads(response.output_text)
except json.JSONDecodeError as exc:
    raise ValueError("The model did not return valid JSON; review or retry the response.") from exc

if not isinstance(invoice, dict):
    raise ValueError("The response must be a JSON object.")

required_keys = {
    "invoice_number", "supplier", "invoice_date", "due_date",
    "amount_due", "currency", "payment_terms", "notes",
}
missing_keys = required_keys - invoice.keys()
if missing_keys:
    raise ValueError(f"The response is missing required keys: {sorted(missing_keys)}")

string_fields = (
    "invoice_number", "supplier", "invoice_date", "due_date", "currency", "payment_terms"
)
for field in string_fields:
    if invoice[field] is not None and not isinstance(invoice[field], str):
        raise ValueError(f"{field} must be a string or null.")

amount = invoice["amount_due"]
if amount is not None and (isinstance(amount, bool) or not isinstance(amount, (int, float))):
    raise ValueError("amount_due must be a number or null.")

if not isinstance(invoice["notes"], list) or not all(
    isinstance(note, str) for note in invoice["notes"]
):
    raise ValueError("notes must be an array of strings.")

print(json.dumps(invoice, indent=2))

OpenAI documents instructions as a string for high-level behavior guidance, alongside input; its official Python quickstart shows the Python client.responses.create(...) pattern. (developers.openai.com) This example separates the prompt (instructions and input) from the API call. It asks for JSON but does not use schema enforcement: parsing and checking the object, keys, and types catches some formatting failures, not incorrect extraction.

A consistent illustrative result for the sample text is:

{
  "invoice_number": "INV-2048",
  "supplier": "Northstar Office Supply",
  "invoice_date": "2026-04-12",
  "due_date": "2026-05-12",
  "amount_due": 684.20,
  "currency": null,
  "payment_terms": "Net 30",
  "notes": ["Currency is ambiguous: '$' does not specify a currency code."]
}

This is an illustrative expected result, not a model test or a guarantee. The source uses a dollar sign but does not identify a currency code, so the prompt leaves currency null and records the ambiguity. If your workflow requires a definite currency, require an explicit code in the source or route ambiguous cases for review.

Make the prompt fit the task

• Name the action and its scope. “Extract these fields from this invoice” is easier to check than “process this invoice.”
• Specify the source of truth. Tell the model whether it must stick to supplied text or may use external sources. For extraction, limiting it to provided material makes unsupported additions easier to spot.
• Define missing-data behavior. Choose a consistent representation—such as null plus a note—and explicitly prohibit guessing.
• Describe the output contract. List field names, types, units, and formatting. Validate the response in your application.
• Keep instructions relevant. Add examples or constraints when they address a real ambiguity or failure in your task.

These are practical prompt-design recommendations, not claims that any particular wording guarantees accuracy. Refine the pattern through testing on your own task.

When to use tools or image input

For text already available to your application, start without tools. A tool is appropriate when the task needs an external action or source—for example, retrieving a file or calling a function in your system. An image input may be useful when the source is a scan or photograph rather than text. GPT-5.4’s model page lists image input and supported Responses API tools, including function calling, web search, file search, and computer use. Tool availability does not configure a tool for your request: follow the relevant API documentation for its setup and call/response flow. (developers.openai.com)

Prompt instructions and tool controls do different jobs. Instructions can tell the model when a tool is relevant or what to do with a result; your API request and application determine which tools are available and what your software does with their outputs. For consequential actions, validate returned data and add any confirmation or human-review steps your workflow requires.

Test the prompt before production

Create a small test set of representative inputs and define observable checks before changing the prompt. For the invoice example, include:

1. A complete invoice with known expected values; check the extracted fields against them.
2. An invoice with a missing due date; check that the value is null and the omission is noted.
3. An invoice with an ambiguous currency symbol, amount, or date; check that the response flags the ambiguity instead of silently choosing an interpretation.
4. Text with extra irrelevant details; check that required fields are still present and unrelated material is not treated as an invoice value.
5. Invalid JSON and valid non-object JSON, such as null or a list; check that the application rejects each instead of treating it as a valid invoice record.

Record which checks pass, revise the prompt or application validation when they fail, and rerun the same cases after each change. Add human review or another safeguard for failures that could cause harm, financial loss, or incorrect records. OpenAI’s prompting guidance recommends tests, representative fixtures, and evaluation checks for prompt changes; that is a workflow recommendation, not evidence that this example has been tested. (developers.openai.com)

Production checklist

• Use the documented model ID and API surface for your application.
• Keep high-level behavior guidance separate from task-specific input.
• Explicitly handle missing and ambiguous information.
• Validate output structure, field types, and business rules in application code.
• Test ordinary, incomplete, ambiguous, invalid-JSON, and non-object inputs.
• Version prompt changes and rerun the same checks before release.
• Add tools or image input only when the task needs them, and verify their configuration separately.

A strong GPT-5.4 prompt is not a magic phrase: it is a clear task specification paired with application-level validation and repeatable tests.

Sources

GPT-5.4 Model — OpenAI API

Text generation — OpenAI API

Developer quickstart — OpenAI API

Prompting — OpenAI API