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

create_message_with_images(text, images \\ nil, opts \\ [])

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"
...> )

has_refusal?(response)

@spec has_refusal?(map()) :: boolean()

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

output_text(response)

@spec output_text(map()) :: String.t()

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"

refusal_message(response)

@spec refusal_message(map()) :: String.t() | nil

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

status(response)

@spec status(map()) :: String.t() | nil

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

token_usage(response)

@spec token_usage(map()) :: map() | nil

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}