OpenAI.Responses.Helpers (openai_responses v0.2.1)
Helper functions for working with OpenAI Responses.
This module provides utility functions for common tasks when working with the OpenAI Responses API, including:
- Extracting text and data from responses
- Creating structured messages with images
- Handling response status and errors
See the individual function documentation for usage examples.
Summary
Functions
Creates a structured message with text and optional images.
Checks if a response contains a refusal.
Extracts the output text from a response.
Gets the refusal message if one exists.
Extracts the status from a response.
Gets token usage information from a response.
Functions
Creates a structured message with text and optional images.
Uses the ImageHelpers module to create a properly formatted message
with text and images for the OpenAI Responses API. See OpenAI.Responses.Helpers.ImageHelpers.create_message_with_images/3
for full documentation.
Examples
# Simple text with one image URL
iex> input_message = OpenAI.Responses.Helpers.create_message_with_images("What is in this image?", "https://example.com/image.jpg")
iex> {:ok, response} = OpenAI.Responses.create("gpt-4o", [input_message])
# With a local file
iex> input_message = OpenAI.Responses.Helpers.create_message_with_images("Describe this", "/path/to/image.jpg")
# With multiple images and high detail
iex> input_message = OpenAI.Responses.Helpers.create_message_with_images(
...> "Compare these",
...> ["image1.jpg", "image2.jpg"],
...> detail: "high"
...> )
Checks if a response contains a refusal.
Parameters
response
- The response from OpenAI.Responses.create/3
Returns
- true if the response contains a refusal, false otherwise
Extracts the output text from a response.
This function navigates the response structure to find and return the generated text. If the response contains multiple outputs or messages, it concatenates them with newlines.
Parameters
response
- The response from OpenAI.Responses.create/3
Returns
- The extracted text as a string
- An empty string if no text output is found
Examples
{:ok, response} = OpenAI.Responses.create("gpt-4o", "Write a haiku about programming")
text = OpenAI.Responses.Helpers.output_text(response)
# => "Fingers tap keyboard
Logic blooms in silent code Bugs hide in plain sight"
Gets the refusal message if one exists.
Parameters
response
- The response from OpenAI.Responses.create/3
Returns
- The refusal message as a string
- nil if no refusal is found
Extracts the status from a response.
Parameters
response
- The response from OpenAI.Responses.create/3
Returns
- The status as a string (e.g., "completed", "in_progress")
- nil if no status is found
Gets token usage information from a response.
Parameters
response
- The response from OpenAI.Responses.create/3
Returns
- A map with token usage information
- nil if no usage information is found
Examples
{:ok, response} = OpenAI.Responses.create("gpt-4o", "Write a haiku about programming")
usage = OpenAI.Responses.Helpers.token_usage(response)
# => %{"input_tokens" => 8, "output_tokens" => 17, "total_tokens" => 25}