OpenAI Responses API: De Ultieme Gids voor Developers

Wat is de Responses API van OpenAI?

De Responses API is OpenAI’s nieuwste en meest geavanceerde API. Het combineert de sterke punten van de Chat Completions- en Assistants-API's in één gestroomlijnde interface. Uitgebracht in maart 2025, behoudt het vertrouwde mogelijkheden en biedt het een meer geïntegreerde aanpak voor het bouwen van AI-applicaties. 

De belangrijkste vernieuwing is hoe het ontwikkeling vereenvoudigt door orkestratielogica automatisch af te handelen en OpenAI’s ingebouwde tools voor websearch en file search native te integreren, zonder dat je eigen implementatie nodig is.

In deze tutorial laten we zien hoe je de Responses API in je projecten gebruikt. Je ziet hoe het tekst genereert, met afbeeldingen werkt en streaming responses levert. We bekijken de ingebouwde tools die ontwikkeling sneller en eenvoudiger maken dan voorheen, en laten zien hoe deze tools samenwerken binnen het framework van de API. 

Aan het einde van deze gids weet je wanneer je de Responses API gebruikt in plaats van andere OpenAI-opties en hoe deze kennis je helpt efficiëntere applicaties te bouwen met minder code en moeite. Als je nieuw bent met de OpenAI API, bekijk dan onze introductiecursus Working with the OpenAI API om je reis te starten naar het ontwikkelen van AI-gedreven applicaties.

Aan de slag met de Responses API

De Responses API biedt een meer gestroomlijnde en gebruiksvriendelijke interface voor interactie met de modellen van OpenAI, waarbij wat eerder een breedsprakige en complexe syntaxis vergde nu is samengebracht in een elegante oplossing. 

Voordat we in specifieke use-cases duiken, richten we onze omgeving in en bekijken we de basis-syntaxis.

from openai import OpenAI
import os
from dotenv import load_dotenv

# Load environment variables from .env file
load_dotenv()

# Initialize the client
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

Deze initialisatiestap maakt een clientobject dat al je API-aanvragen afhandelt. Het pakket dotenv helpt je API-sleutel veilig te beheren via omgevingsvariabelen in plaats van deze in je script te hardcoden — een best practice die je code draaglijker en veiliger maakt over verschillende omgevingen heen.

Content genereren met de Responses API

De meest directe toepassing van de Responses API is het genereren van tekstcontent. Laten we een realistische situatie verkennen: stel dat je een e-commerceplatform bouwt en automatisch overtuigende productbeschrijvingen moet genereren op basis van basisproductdetails.

Traditioneel vereiste dit zorgvuldige prompt engineering en meerdere iteraties. Met de Responses API kun je een eenvoudige functie maken die dit elegant afhandelt:

def generate_product_description(product_name, features, target_audience):
   response = client.responses.create(
       model="gpt-4o",
       instructions="You are a professional copywriter specialized in creating concise, compelling product descriptions. Focus on benefits rather than just features.",
       input=f"""
       Create a product description for {product_name}.
       Key features:
       - {features[0]}
       - {features[1]}
       - {features[2]}
       Target audience: {target_audience}
       Keep it under 150 words.
       """,
       temperature=0.7,
       max_output_tokens=200
   )
  
   return response.output_text

# Example usage
headphones_desc = generate_product_description(
   "NoiseGuard Pro Headphones",
   ["Active noise cancellation", "40-hour battery life", "Memory foam ear cushions"],
   "Business travelers and remote workers"
)

print(headphones_desc)

Output:

Experience unparalleled focus and comfort with NoiseGuard Pro Headphones—your perfect travel and work companion. 
Designed for business travelers and remote workers, these headphones feature cutting-edge active noise cancellation to block out distractions, allowing you to concentrate on what truly matters. 
With an impressive 40-hour battery life, you can enjoy uninterrupted productivity or relaxation on even the longest journeys. 
The luxurious memory foam ear cushions ensure a snug, comfortable fit for all-day wear, reducing fatigue and enhancing your listening experience. 
Elevate your work and travel with NoiseGuard Pro—where clarity meets comfort.

Met slechts een paar regels code hebben we marketingwaardige copy gecreëerd die normaal gesproken een professionele schrijver vereist. De functie is ook herbruikbaar — pas simpelweg de parameters aan en je kunt beschrijvingen genereren voor elk product in je catalogus.

Dit voorbeeld laat sleutelpatronen zien bij het gebruik van de Responses API:

1. De parameter instructions fungeert als een systeemprompt die het gedrag en de context van de AI bepaalt.
2. De parameter temperature (0-2) stuurt de willekeurigheid aan—lagere waarden leveren deterministischer output op, hogere waarden zorgen voor meer creativiteit.
3. De parameter max_output_tokens beperkt de lengte van de response, wat helpt om kosten te beheersen en bondige output te garanderen.
4. Het responseobject bevat de gegenereerde tekst in de eigenschap output_text.

Afbeeldingen analyseren voor praktische toepassingen

Veel realistische applicaties moeten zowel tekst als afbeeldingen verwerken. E-commerceplatforms moeten bijvoorbeeld productfoto's analyseren, systemen voor contentmoderatie moeten uploads beoordelen en socialmedia-apps moeten visuele content begrijpen.

De Responses API blinkt uit in multimodale taken zoals beeldanalyse zonder aparte endpoints of complexe integratiecode te vereisen:

def analyze_product_image(image_url):
   response = client.responses.create(
       model="gpt-4o",
       instructions="You are a product photography expert and e-commerce consultant.",
       input=[
           {"role": "user", "content": "Analyze this product image and provide the following details:\n1. Product category\n2. Key visible features\n3. Potential quality issues\n4. Suggested improvements for the product photography"},
           {
               "role": "user",
               "content": [
                   {
                       "type": "input_image",
                       "image_url": image_url
                   }
               ],
           },
       ],
       temperature=0.2
   )
  
   return response.output_text

# Example with a sports team image
analysis = analyze_product_image("https://upload.wikimedia.org/wikipedia/commons/a/a5/Barcelona_fc_lamina_elgrafico.jpg")
print(analysis)

Output:

1. **Product Category**: Sports team memorabilia or vintage sports photography.

2. **Key Visible Features**:
  - The image features a group of individuals in sports uniforms, likely a football (soccer) team.
  - The uniforms have distinct vertical stripes in red and blue.
  - A football is visible in the foreground.
  - The setting appears to be an outdoor field, possibly a stadium.

...

Deze functie kan worden geïntegreerd in een e-commerceplatform om productfoto's automatisch te analyseren wanneer verkopers ze uploaden. Het systeem kan direct feedback geven over de beeldkwaliteit en verbeteringen voorstellen, wat uiteindelijk leidt tot hogere conversies dankzij betere vermeldingen — zonder handmatige beoordeling.

Bij het werken met afbeeldingen geef je een array van berichtobjecten door aan de inputparameter in plaats van een string, elk met een role- en contentwaarde.

 Afbeeldingscontent specificeer je als een object met type: input_image en een image_url. Je kunt tekst en afbeeldingen in dezelfde aanvraag combineren, wat rijke multimodale interacties mogelijk maakt.

Streaming implementeren voor responsieve applicaties

Gebruikers verwachten direct feedback. Enkele seconden wachten op een AI-antwoord kan de betrokkenheid de das om doen — daarom is streaming essentieel voor responsieve user experiences, vooral in chat- of realtime-applicaties.

Stel je bouwt een tool voor klantfeedbackanalyse voor een productteam. In plaats van ze te laten wachten op de volledige analyse, kun je de resultaten streamen terwijl ze worden gegenereerd:

def analyze_customer_feedback(feedback_text):
   print("Analyzing customer feedback in real-time:")
  
   stream = client.responses.create(
       model="gpt-4o",
       instructions="Extract key sentiments, product issues, and actionable insights from this feedback.",
       input=feedback_text,
       stream=True,
       temperature=0.3,
       max_output_tokens=500
   )
  
   full_response = ""
   print("\nAnalysis results:")
   for event in stream:
       if event.type == "response.output_text.delta":
           print(event.delta, end="")
           full_response += event.delta
       elif event.type == "response.error":
           print(f"\nError occurred: {event.error}")
  
   return full_response

# Example with a complex customer review
feedback = """
I've been using the SmartHome Hub for about 3 months now. The voice recognition is fantastic
and the integration with my existing devices was mostly seamless. However, the app crashes
at least once a day, and the night mode feature often gets stuck until I restart the system.
Customer support was helpful but couldn't fully resolve the app stability issues.
"""

analysis_result = analyze_customer_feedback(feedback)

In een echte applicatie zou je de print-statements vervangen door UI-updates, zodat je gebruikers de analyse in realtime zien ontstaan—net zoals moderne chatapplicaties laten zien dat de AI "aan het nadenken" is terwijl een antwoord wordt gegenereerd. Dit zorgt voor een meer betrokken ervaring en geeft gebruikers direct bevestiging dat hun verzoek wordt verwerkt.

De streaming-implementatie werkt door:

1. stream=True in te stellen in de creatiemethode
2. De response te verwerken als een iterabele van events met specifieke types
3. Verschillende eventtypes apart af te handelen: response.output_text.delta voor contentchunks, response.error voor fouten

Nu we de basisfunctionaliteit van de Responses API hebben behandeld, bekijken we de ingebouwde tools die de mogelijkheden verder uitbreiden.

Ingebouwde tools van de OpenAI Responses API

De Responses API integreert een aantal ingebouwde tools die de mogelijkheden verder brengen dan alleen tekstgeneratie. Met deze tools kunnen developers krachtigere applicaties maken zonder complexe integratiecode of meerdere API-calls.

Websearch: realtime informatie raadplegen

De websearch-tool stelt de Responses API in staat om actuele informatie van internet op te halen, waarmee de beperking wordt aangepakt dat LLM's zijn beperkt tot hun trainingsdata.

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
   model="gpt-4o",
   tools=[{"type": "web_search_preview"}],
   input="What are some news related to the stock market?",
)

print(response.output_text)

Output:

Recent developments in the stock market have been significantly influenced by escalating trade tensions between the United States and China. On April 5, 2025, President Donald Trump announced an additional 34% tariff on Chinese goods, raising total tariffs to 54% this year. In response, China imposed reciprocal 34% tariffs on U.S. products and introduced export restrictions on certain rare earth elements. These actions led to a sharp global market selloff, with the S&P 500 falling 9% for the week, marking the steepest decline since the pandemic. (reuters.com)

…..


## Escalating US-China Trade Tensions Impact Global Markets:
- [China says 'market has spoken' after US tariffs spark selloff](https://www.reuters.com/world/china/china-says-market-has-spoken-after-us-tariffs-spark-selloff-2025-04-05/?utm_source=openai)
- [Trump touts "economic revolution" as economists warn of recession](https://www.axios.com/2025/04/05/trump-tariffs-stock-market-recession?utm_source=openai)
- [Believe it or not, there were some winners in the stock market this week](https://apnews.com/article/ce81e9ae6fb463dc763dfaa464778343?utm_source=openai)

De websearch-tool voert bij activering meerdere bewerkingen uit, van het analyseren van de query tot het synthetiseren van informatie uit meerdere bronnen met correcte verwijzingen. Deze mogelijkheid opent de deur naar informatieve applicaties zoals tools voor financiële analyse die marktinzichten leveren, nieuwsaggregatieplatforms die meerdere bronnen combineren, of educatieve resources die kerncontent aanvullen met actueel onderzoek.

Een belangrijk voordeel van deze tool is het kunnen leveren van actuele informatie zonder een eigen zoekintegratie of webscrapingsysteem te hoeven bouwen en onderhouden. De tool handelt het zoekproces af en presenteert resultaten met correcte bronvermelding om transparantie over informatiebronnen te waarborgen.

File search: informatie uit documenten halen

Waar websearch externe kennis in je applicatie brengt, richt de file search-tool zich op het ontsluiten van informatie uit documenten. Deze tool stelt de API in staat te zoeken in en informatie te extraheren uit documenten die naar OpenAI zijn geüpload.

De file search-tool maakt meerdere kernmogelijkheden mogelijk:

• Zoeken in meerdere bestandstypen (pdf’s, Word-documenten, presentaties, enz.).
• Specifieke informatie vinden binnen documenten op basis van natuurlijke taalqueries.
• Informatie uit meerdere documenten tegelijk extraheren en synthetiseren.
• Verwijzingen geven naar specifieke secties van de brondocumenten.
• Complexe queries ondersteunen die naar informatie over meerdere bestanden verwijzen.

Deze mogelijkheid is zeer geschikt voor documentanalyse, zoals informatie uit juridische contracten halen, onderzoekspapers analyseren of knowledge bases opbouwen uit technische documentatie. De tool kan relevante secties over meerdere documenten identificeren en informatie synthetiseren als antwoord op specifieke queries.

De implementatie vereist dat je eerst bestanden uploadt naar OpenAI’s files-endpoint en vervolgens de bestands-ID’s doorgeeft aan de Responses API bij een query. Dit creëert een gestroomlijnde workflow voor applicaties die specifieke informatie in documenten moeten raadplegen, zonder dat gebruikers handmatig hoeven te zoeken.

Computer use: interactie met interfaces

Voortbouwend op het fundament van tekst- en documentbegrip, breidt de computer use-tool AI-mogelijkheden uit naar het domein van interface-interactie. Deze tool is een belangrijke stap voorwaarts die de kloof overbrugt tussen taalbegrip en bediening van gebruikersinterfaces.

De computer use-tool kan verschillende interface-interacties uitvoeren:

• Autonoom door websites en webapps navigeren.
• Formulieren invullen met passende informatie.
• Data extraheren uit webpagina’s en applicaties.
• Meertrapsprocessen uitvoeren over verschillende schermen.
• Interactie met elementen zoals knoppen, keuzelijsten en tekstvelden.
• De context en het doel van verschillende interface-elementen begrijpen.

Potentiële toepassingen zijn procesautomatisering voor repetitieve taken, begeleide assistentie voor complexe workflows en toegankelijkheidsverbeteringen voor gebruikers die moeite hebben met traditionele interfaces. De tool kan worden ingezet om formulieren te automatiseren, door complexe websites te navigeren of UI-tests uit te voeren.

De technologie werkt door de AI toegang te geven tot schermonderdelen, context te laten begrijpen en acties uit te voeren op basis van instructies in natuurlijke taal. Dit creëert mogelijkheden voor automatisering en assistentie die anders specifieke ontwikkeling van interfacecode vereisen.

Aanvullende toolmogelijkheden

Het ecosysteem van tools binnen de Responses API blijft groeien, waarbij OpenAI regelmatig nieuwe mogelijkheden toevoegt. De uitgebreide documentatie over tools behandelt implementatiedetails voor alle momenteel beschikbare tools, terwijl het artikel over nieuwe tools voor het bouwen van agents strategische context biedt over hoe deze tools zich ontwikkelen.

Deze ingebouwde tools bieden krachtige mogelijkheden out-of-the-box, maar veel applicaties moeten verbinden met gespecialiseerde services of propriëtaire systemen. Hier wordt function calling essentieel, waarmee je de Responses API kunt uitbreiden met je eigen custom tools en externe services — de focus van onze volgende sectie.

Function calling in de Responses API

Hoewel ingebouwde tools krachtige mogelijkheden bieden, moeten veel applicaties verbinden met gespecialiseerde services of propriëtaire systemen. Function calling stelt je in staat de Responses API uit te breiden met je eigen custom tools, zodat het model kan bepalen wanneer en hoe je functies worden aangeroepen op basis van gebruikersinput.

Function calling creëert een brug tussen het taalbegrip van de AI en je externe systemen — of dat nu het ophalen van wisselkoersen is, afstanden berekenen of beschikbaarheid van afspraken controleren. Dit patroon volgt een duidelijke workflow:

1. Je definieert functies die de AI kan gebruiken, met specificatie van parameters en hun types.
2. De AI beslist wanneer deze functies worden aangeroepen op basis van gebruikersvragen.
3. Je code voert de functies uit met de door de AI geleverde parameters.
4. Je retourneert de resultaten aan de AI, die ze verwerkt in zijn antwoord.

Een tool voor valutaconversie maken

Laten we als voorbeeld een eenvoudige functie voor valutaconversie implementeren:

# Dictionary of exchange rates (relative to USD)
exchange_rates = {
   "USD": 1.0,
   "EUR": 0.93,
   "GBP": 0.79,
   "JPY": 153.2,
   "CAD": 1.37,
   "AUD": 1.52
}

def convert_currency(amount, from_currency, to_currency):
   """Convert an amount from one currency to another."""
   # Normalize currency codes to uppercase
   from_currency = from_currency.upper()
   to_currency = to_currency.upper()
  
   # Check if currencies are supported
   if from_currency not in exchange_rates:
       return {"error": f"Currency not supported: {from_currency}"}
   if to_currency not in exchange_rates:
       return {"error": f"Currency not supported: {to_currency}"}
  
   # Convert to USD first, then to target currency
   amount_in_usd = amount / exchange_rates[from_currency]
   converted_amount = amount_in_usd * exchange_rates[to_currency]
  
   return {
       "original_amount": amount,
       "from_currency": from_currency,
       "to_currency": to_currency,
       "converted_amount": round(converted_amount, 2)
   }

Deze functie neemt drie parameters: het bedrag om te converteren, de bronvaluta en de doelvaluta. Hij voert een eenvoudige conversie uit met vooraf gedefinieerde wisselkoersen en retourneert een gestructureerd resultaat met de conversiedetails.

De functie definiëren voor de Responses API

Nu moeten we het model vertellen over onze functie, zodat het kan bepalen wanneer deze aan te roepen:

from openai import OpenAI
import json

client = OpenAI()

tools = [
   {
       "type": "function",
       "name": "convert_currency",
       "description": "Convert an amount from one currency to another using current exchange rates",
       "parameters": {
           "type": "object",
           "properties": {
               "amount": {
                   "type": "number",
                   "description": "The amount of money to convert"
               },
               "from_currency": {
                   "type": "string",
                   "description": "The currency code to convert from (e.g., USD, EUR, GBP)"
               },
               "to_currency": {
                   "type": "string",
                   "description": "The currency code to convert to (e.g., USD, EUR, GBP)"
               }
           },
           "required": ["amount", "from_currency", "to_currency"],
           "additionalProperties": False
       },
       "strict": True
   }
]

Deze definitie specificeert duidelijk:

• De functienaam convert_currency die overeenkomt met onze Python-functie.
• Een beschrijving die uitlegt wanneer de functie moet worden gebruikt.
• Drie vereiste parameters met hun types en beschrijvingen.
• De vlag strict: true om ervoor te zorgen dat het model onze parameterspecificaties exact volgt.

Een gebruikersvraag afhandelen

Laten we een gesprek simuleren waarin een gebruiker vraagt naar een valutaconversie:

input_messages = [
   {"role": "user", "content": "How much is 100 euros in Japanese yen?"}
]

response = client.responses.create(
   model="gpt-4o",
   input=input_messages,
   tools=tools,
)

Wanneer het model deze vraag over valutaconversie ziet, herkent het dat onze functie moet worden gebruikt. Het identificeert automatisch dat:

• Het bedrag 100 is
• De bronvaluta euro (EUR) is
• De doelvaluta Japanse yen (JPY) is

De functieaanroep verwerken

Nu halen we de details van de functieaanroep op en voeren we onze functie uit:

tool_call = response.output[0]
print(f"Function called: {tool_call.name}")
print(f"Arguments: {tool_call.arguments}")

args = json.loads(tool_call.arguments)

# Execute the function with the parameters determined by the model
conversion_result = convert_currency(**args)
print(f"Function results: {conversion_result}")

Het model heeft de natuurlijke taalvraag vertaald naar gestructureerde parameters. Onze functie voert vervolgens de berekening uit op basis van deze parameters en retourneert het geconverteerde bedrag.

Functieresultaten teruggeven aan het model

Tot slot sturen we de resultaten terug naar het model, zodat het een gebruiksvriendelijk antwoord kan genereren:

input_messages.append(tool_call)  # append model's function call message
input_messages.append(
   {  # append result message
       "type": "function_call_output",
       "call_id": tool_call.call_id,
       "output": json.dumps(conversion_result)
   }
)

response_2 = client.responses.create(
   model="gpt-4o",
   input=input_messages,
   tools=tools,
)
print(response_2.output_text)

Output:

100 euros is equal to 16,473.12 Japanese yen based on current exchange rates.

Het model heeft onze ruwe conversiedata omgezet in een natuurlijk, leesbaar antwoord. Het heeft het numerieke resultaat correct geïnterpreteerd en in een passend valutaformaat gepresenteerd.

Alles samenbrengen

In een echte applicatie wil je dit gehele proces kapselen in één interface die de conversatiestroom naadloos afhandelt. Zo zou je een complete assistent kunnen maken die het hele function-callingproces beheert:

def currency_assistant(user_message, conversation_history=None):
   """A complete assistant that handles currency conversion queries."""
   if conversation_history is None:
       conversation_history = []
  
   # Add the user's new message to the conversation
   conversation_history.append({"role": "user", "content": user_message})
  
   # Define available tools (our currency conversion function)
   tools = [{
       "type": "function",
       "name": "convert_currency",
       "description": "Convert an amount from one currency to another using current exchange rates",
       "parameters": {
           "type": "object",
           "properties": {
               "amount": {
                   "type": "number",
                   "description": "The amount of money to convert"
               },
               "from_currency": {
                   "type": "string",
                   "description": "The currency code to convert from (e.g., USD, EUR, GBP)"
               },
               "to_currency": {
                   "type": "string",
                   "description": "The currency code to convert to (e.g., USD, EUR, GBP)"
               }
           },
           "required": ["amount", "from_currency", "to_currency"],
           "additionalProperties": False
       },
       "strict": True
   }]
  
   # Get initial response from the model
   response = client.responses.create(
       model="gpt-4o",
       input=conversation_history,
       tools=tools,
   )
  
   # Check if the model wants to call a function
   if response.output and isinstance(response.output, list) and response.output[0].type == "function_call":
       tool_call = response.output[0]
      
       # Process the function call
       args = json.loads(tool_call.arguments)
       result = convert_currency(**args)
      
       # Add the function call and its result to the conversation
       conversation_history.append(tool_call)
       conversation_history.append({
           "type": "function_call_output",
           "call_id": tool_call.call_id,
           "output": json.dumps(result)
       })
      
       # Get the final response with the function results incorporated
       final_response = client.responses.create(
           model="gpt-4o",
           input=conversation_history,
           tools=tools,
       )
      
       return final_response.output_text, conversation_history
   else:
       # If no function call was needed, return the direct response
       return response.output_text, conversation_history

# Example usage
response, conversation = currency_assistant("How much is 50 British pounds in Australian dollars?")
print("Assistant:", response)

# Continue the conversation
response, conversation = currency_assistant("And what if I wanted to convert 200 Canadian dollars instead?", conversation)
print("Assistant:", response)

Deze implementatie:

1. Beheert de gespreksgeschiedenis om context te bieden voor vervolgvragen.
2. Handelt het hele proces van function calling af binnen één interface.
3. Bepaalt wanneer function calling nodig is en wanneer het model direct kan antwoorden.
4. Ondersteunt meerdaagse gesprekken waarin eerdere context telt.

Met deze aanpak kun je naadloze conversatie-ervaringen creëren waarin gebruikers natuurlijk interacteren, zonder zich bewust te zijn van de complexe function calling achter de schermen. De assistent verzorgt de overgang tussen taalbegrip, gestructureerde functieaanroepen en natuurlijke taalgeneratie.

Complexere applicaties bouwen kan inhouden:

1. Ondersteuning voor meerdere functies, elk voor verschillende soorten queries.
2. Authenticatie en autorisatie beheren voor gevoelige operaties.
3. Geavanceerdere foutafhandeling en -herstel implementeren.
4. Logging en monitoring toevoegen voor functiegebruik en prestaties.
5. Gebruikersinterfaces maken die tekst, spraak of multimodale interacties ondersteunen.

Function calling verbindt de Responses API met je services en data via natuurlijke taalinput. Dit creëert een brug tussen gebruikersverzoeken en je bedrijfssystemen, zodat gebruikers in gewone taal kunnen vragen terwijl jouw applicatie de technische implementatiedetails achter de schermen afhandelt.

Naast function calling is een andere krachtige mogelijkheid van de Responses API het genereren van gestructureerde outputs. Deze functie vult function calling aan door een manier te bieden om responses in specifieke formaten te ontvangen die aansluiten op de behoeften van je applicatie.

Gestructureerde outputs met de Responses API

Bij het bouwen van AI-applicaties heb je vaak responses in een specifiek formaat nodig om eenvoudiger met je systemen te integreren. De Responses API ondersteunt gestructureerde outputs waarmee je data ontvangt in een goed gedefinieerd, consistent formaat in plaats van vrije tekst. Deze functie is vooral waardevol wanneer je moet:

1. Specifieke informatie uit ongestructureerde tekst extraheren.
2. Gebruikersinvoer omzetten in gestructureerde data.
3. Consistente responseformaten garanderen voor downstreamverwerking.
4. AI-outputs direct integreren met databases of API’s.

Gestructureerde outputs verminderen de noodzaak voor extra parsing en validatie, waardoor je applicaties robuuster en onderhoudsvriendelijker worden.

Productinformatie uit beschrijvingen extraheren

Laten we een praktisch voorbeeld bekijken: stel dat je een e-commerceplatform bouwt en automatisch productdetails wilt extraheren uit ongestructureerde productbeschrijvingen om je database te vullen.

from openai import OpenAI
import json

client = OpenAI()

product_description = """
Our Premium Laptop Backpack is perfect for professionals and students alike.
Made with water-resistant material, it features padded compartments that fit
laptops up to 15.6 inches. The backpack includes 3 main storage areas,
5 smaller pockets, and has an integrated USB charging port. Available in
navy blue, black, and gray. Current retail price: $79.99, though it's
currently on sale for $64.99 until the end of the month.
"""

response = client.responses.create(
   model="gpt-4o",
   input=f"Extract structured product information from this description: {product_description}",
   text={
       "format": {
           "type": "json_schema",
           "name": "product_details",
           "schema": {
               "type": "object",
               "properties": {
                   "product_name": {"type": "string"},
                   "category": {"type": "string"},
                   "features": {"type": "array", "items": {"type": "string"}},
                   "colors": {"type": "array", "items": {"type": "string"}},
                   "pricing": {
                       "type": "object",
                       "properties": {
                           "regular_price": {"type": "number"},
                           "sale_price": {"type": "number"},
                           "currency": {"type": "string"},
                       },
                       "additionalProperties": False,
                       "required": ["regular_price", "sale_price", "currency"],
                   },
               },
               "required": ["product_name", "features", "colors", "pricing","category"],
               "additionalProperties": False,
           },
           "strict": True,
       }
   },
)

product_data = json.loads(response.output_text)
print(json.dumps(product_data, indent=2))

Output:

{
 "product_name": "Premium Laptop Backpack",
 "category": "Backpack",
 "features": [
   "Water-resistant material",
   "Padded compartments for laptops up to 15.6 inches",
   "3 main storage areas",
   "5 smaller pockets",
   "Integrated USB charging port"
 ],
 "colors": [
   "Navy blue",
   "Black",
   "Gray"
 ],
 "pricing": {
   "regular_price": 79.99,
   "sale_price": 64.99,
   "currency": "USD"
 }
}

Deze geformatteerde JSON-data kan nu direct worden geïntegreerd met je productdatabase, wat de noodzaak voor eigen parse-logica elimineert en de kans op fouten verkleint.

De configuratie van gestructureerde output begrijpen

De sleutel tot effectieve en foutloze gestructureerde outputs is je schema correct definiëren. Laten we de belangrijke elementen van de configuratie uitsplitsen:

text={
   "format": {
       "type": "json_schema",        # Specifies we're using JSON Schema
       "name": "product_details",    # A descriptive name for this schema
       "schema": {
           # Your JSON Schema definition here
           "type": "object",
           "properties": {
               # Each property with type information, e.g.
               "product_name": {"type": "string"},
               # ... other properties
           },
           "required": ["product_name", ...], # All other properties
           "additionalProperties": False
       },
       "strict": True                # Enforce schema constraints strictly
   }
}

De belangrijkste componenten zijn:

1. Schemadefinitie: beschrijft de structuur, inclusief alle properties en hun types.
2. Vereiste velden: lijst met properties die in de response moeten staan.
3. Additional properties: wanneer ingesteld op False, voorkomt extra velden die niet in het schema zijn gedefinieerd.
4. Strikte modus: wanneer True, zorgt dit dat het model het schema precies volgt.

Praktische tips voor het gebruik van gestructureerde outputs

Volg voor de beste resultaten met gestructureerde outputs deze richtlijnen:

1. Ontwerp je schema zorgvuldig: neem alle vereiste velden op, maar houd het gericht op essentiële informatie.
2. Gebruik passende datatypes: stem je schematypes af op hoe je de data gebruikt (nummers voor berekeningen, strings voor tekst).
3. Stel duidelijke beperkingen in: gebruik enum voor velden met beperkte opties en minimum/maximum voor numerieke grenzen.
4. Test met gevarieerde input: zorg dat je schema verschillende inputformaten en randgevallen aankan.
5. Voeg duidelijke beschrijvingen toe: beschrijvingen bij velden helpen het model te interpreteren welke informatie moet worden geëxtraheerd.

Vergelijking met de Chat Completions API

Hoewel de Responses API gestructureerde outputs via JSON Schema biedt, heeft de Chat Completions API een alternatieve aanpak met Pydantic-modellen die veel eenvoudiger is:

from pydantic import BaseModel, Field
from typing import List, Optional
from openai import OpenAI

client = OpenAI()

class ProductDetails(BaseModel):
   product_name: str
   category: str = Field(default=None)
   features: List[str]
   specifications: Optional[dict] = None
   colors: List[str]
   pricing: dict

# With Chat Completions API
completion = client.beta.chat.completions.parse(
   model="gpt-4o",
   messages=[
       {"role": "system", "content": "Extract structured product information."},
       {"role": "user", "content": product_description}
   ],
   response_format=ProductDetails
)

pydantic_product = completion.choices[0].message.parsed

Elke aanpak heeft z’n voordelen:

• Responses API gebruikt standaard JSON Schema direct in de API-call
• Chat Completions API integreert met het typesysteem van Python via Pydantic

Als je het mij vraagt, zou ik de Chat Completions API gebruiken zodat ik geen ruwe JSON-schema’s hoef te schrijven. Tenzij, natuurlijk, OpenAI ondersteuning voor Pydantic-modellen toevoegt aan de Responses API.

Voor meer informatie, bekijk de documentatie van de Responses API over Structured Outputs.

Conclusie

De OpenAI Responses API vereenvoudigt hoe developers met taalmodellen werken door de sterke punten van eerdere API’s te combineren in één uniforme interface die minder code en complexiteit vereist. De API ondersteunt tekstgeneratie, beeldanalyse, function calling en gestructureerde outputs, waardoor AI-mogelijkheden toegankelijker worden en developers zich kunnen richten op het oplossen van zakelijke problemen in plaats van integratie-uitdagingen.

Als je verdergaat met de Responses API, vind je deze extra resources wellicht handig om je begrip te verdiepen en je implementatievaardigheden uit te breiden:

• Working with the OpenAI API
• OpenAI Fundamentals Track
• GPT-4.5: What’s New in OpenAI’s Latest Model
• Deep Research with OpenAI
• GPT-4.5 Function Calling Tutorial
• GPT-4.5 API Tutorial
• OpenAI Agents SDK Tutorial