module AI::OpenAI

Overview

Version string of this package.

Defined in:

Constant Summary

API_KEY_ENV_VAR = "OPENAI_API_KEY"

Environment variable for API key.

BASE_URL_ENV_VAR = "OPENAI_BASE_URL"

Environment variable for base URL.

DEFAULT_BASE_URL = "https://api.openai.com/v1"

Default base URL for OpenAI API.

DEFAULT_IMAGE_MAX_IMAGES_PER_CALL = 1

Default max images when model is unknown.

DEFAULT_PROVIDER_NAME = "openai"

Default provider name.

DEFAULT_RESPONSE_FORMAT_PREFIXES = ["gpt-image-1-mini", "gpt-image-1.5", "gpt-image-1"]

Model prefixes that have default response format (don't need response_format=b64_json).

LANGUAGE_MAP = {"afrikaans" => "af", "arabic" => "ar", "armenian" => "hy", "azerbaijani" => "az", "belarusian" => "be", "bosnian" => "bs", "bulgarian" => "bg", "catalan" => "ca", "chinese" => "zh", "croatian" => "hr", "czech" => "cs", "danish" => "da", "dutch" => "nl", "english" => "en", "estonian" => "et", "finnish" => "fi", "french" => "fr", "galician" => "gl", "german" => "de", "greek" => "el", "hebrew" => "he", "hindi" => "hi", "hungarian" => "hu", "icelandic" => "is", "indonesian" => "id", "italian" => "it", "japanese" => "ja", "kannada" => "kn", "kazakh" => "kk", "korean" => "ko", "latvian" => "lv", "lithuanian" => "lt", "macedonian" => "mk", "malay" => "ms", "marathi" => "mr", "maori" => "mi", "nepali" => "ne", "norwegian" => "no", "persian" => "fa", "polish" => "pl", "portuguese" => "pt", "romanian" => "ro", "russian" => "ru", "serbian" => "sr", "slovak" => "sk", "slovenian" => "sl", "spanish" => "es", "swahili" => "sw", "swedish" => "sv", "tagalog" => "tl", "tamil" => "ta", "thai" => "th", "turkish" => "tr", "ukrainian" => "uk", "urdu" => "ur", "vietnamese" => "vi", "welsh" => "cy"}

Language mapping for OpenAI speech-to-text. Maps full language names to ISO-639-1 codes. https://platform.openai.com/docs/guides/speech-to-text#supported-languages

MODEL_MAX_IMAGES_PER_CALL = {"dall-e-3" => 1, "dall-e-2" => 10, "gpt-image-1" => 10, "gpt-image-1-mini" => 10, "gpt-image-1.5" => 10}

Maximum images per call for known models.

MODELS_SUPPORTING_VERBOSE_JSON = ["whisper-1"]

Models that support verbose_json format with segments.

MODELS_WITHOUT_VERBOSE_JSON = ["gpt-4o-transcribe", "gpt-4o-mini-transcribe"]

Models that only support json format (no verbose_json).

OPENAI_CHAT_MODEL_IDS = ["o1", "o1-2024-12-17", "o3", "o3-2025-04-16", "o3-mini", "o3-mini-2025-01-31", "o4-mini", "o4-mini-2025-04-16", "gpt-4.1", "gpt-4.1-2025-04-14", "gpt-4.1-mini", "gpt-4.1-mini-2025-04-14", "gpt-4.1-nano", "gpt-4.1-nano-2025-04-14", "gpt-4o", "gpt-4o-2024-05-13", "gpt-4o-2024-08-06", "gpt-4o-2024-11-20", "gpt-4o-mini", "gpt-4o-mini-2024-07-18", "gpt-4", "gpt-4-0613", "gpt-4-turbo", "gpt-4-turbo-2024-04-09", "gpt-4.5-preview", "gpt-4.5-preview-2025-02-27", "gpt-3.5-turbo", "gpt-3.5-turbo-0125", "gpt-3.5-turbo-1106", "chatgpt-4o-latest", "gpt-5", "gpt-5-2025-08-07", "gpt-5-mini", "gpt-5-mini-2025-08-07", "gpt-5-nano", "gpt-5-nano-2025-08-07", "gpt-5-chat-latest", "gpt-5.1", "gpt-5.1-chat-latest", "gpt-5.2", "gpt-5.2-chat-latest", "gpt-5.2-pro"]

Known OpenAI chat model IDs.

OPENAI_EMBEDDING_MODEL_IDS = ["text-embedding-3-small", "text-embedding-3-large", "text-embedding-ada-002"]

Known OpenAI embedding model IDs.

OPENAI_SPEECH_MODEL_IDS = ["tts-1", "tts-1-hd", "gpt-4o-mini-tts"]

Valid OpenAI TTS model IDs.

OPENAI_TRANSCRIPTION_MODEL_IDS = ["whisper-1", "gpt-4o-mini-transcribe", "gpt-4o-transcribe"]

Valid OpenAI transcription model IDs.

SUPPORTED_SPEECH_FORMATS = ["mp3", "opus", "aac", "flac", "wav", "pcm"]

Supported audio formats for speech generation.

TRANSCRIPTION_RESPONSE_FORMATS = ["json", "verbose_json", "text", "srt", "vtt"]

Supported response formats for transcription.

• json: Simple JSON with text only
• verbose_json: JSON with segments and word-level timing
• text: Plain text
• srt: SRT subtitle format
• vtt: VTT subtitle format

VALID_CHAT_PROVIDER_OPTIONS = ["logitBias", "logprobs", "parallelToolCalls", "user", "reasoningEffort", "maxCompletionTokens", "store", "metadata", "prediction", "serviceTier", "strictJsonSchema", "textVerbosity", "promptCacheKey", "promptCacheRetention", "safetyIdentifier", "systemMessageMode", "forceReasoning"]

Valid provider option keys for chat language models.

VALID_EMBEDDING_PROVIDER_OPTIONS = ["dimensions", "user"]

Valid provider option keys for embedding models.

VALID_IMAGE_PROVIDER_OPTIONS = ["style", "quality", "background", "output_format", "output_compression", "input_fidelity", "user", "response_format"]

Valid provider options for OpenAI Image API.

VERSION = "0.1.0"

Class Method Summary

• .convert_openai_chat_usage(usage : OpenAIChatUsage | Nil) : Provider::LanguageModel::Usage

  Converts OpenAI chat usage to SDK usage format.

• .convert_to_openai_chat_messages(prompt : Array(Provider::LanguageModel::Message), system_message_mode : SystemMessageMode = SystemMessageMode::System) : ConvertMessagesResult

  Converts SDK language model prompt to OpenAI chat messages format.

• .create_openai(base_url : String | Nil = nil, api_key : String | Nil = nil, organization : String | Nil = nil, project : String | Nil = nil, headers : Hash(String, String) | Nil = nil, name : String | Nil = nil) : OpenAIProvider

  Creates an OpenAI provider instance.

• .error_to_message(data : OpenAIErrorData) : String

  Extracts the error message from OpenAI error data.

• .get_model_max_images_per_call(model_id : String) : Int32

  Gets the maximum images per call for a model.

• .get_openai_language_model_capabilities(model_id : String) : OpenAILanguageModelCapabilities

  Returns the capabilities for a given OpenAI model ID.

• .get_response_metadata(id : String | Nil = nil, model : String | Nil = nil, created : Int64 | Nil = nil) : Provider::LanguageModel::ResponseMetadata

  Extracts response metadata from OpenAI API response fields.

• .has_default_response_format?(model_id : String) : Bool

  Checks if the model has a default response format.

• .language_to_code(language : String | Nil) : String | Nil

  Converts a language name to ISO-639-1 code.

• .map_openai_finish_reason(finish_reason : String | Nil) : Provider::LanguageModel::UnifiedFinishReason

  Maps OpenAI finish reason strings to unified finish reasons.

• .openai : OpenAIProvider

  Default OpenAI provider instance.

• .parse_chat_provider_options(provider_options : Hash(String, JSON::Any), provider_name : String) : OpenAIChatProviderOptions | Nil

  Parses chat provider options from the provider options hash.

• .parse_embedding_provider_options(provider_options : Hash(String, JSON::Any), provider_name : String) : OpenAIEmbeddingProviderOptions | Nil

  Parses embedding provider options from the provider options hash.

• .parse_openai_speech_provider_options(provider_options : Provider::Shared::ProviderOptions | Nil) : OpenAISpeechProviderOptions | Nil

  Parse OpenAI speech provider options from ProviderOptions hash.

• .parse_openai_transcription_provider_options(provider_options : Provider::Shared::ProviderOptions | Nil) : OpenAITranscriptionProviderOptions | Nil

  Parse OpenAI transcription provider options from ProviderOptions hash.

• .prepare_chat_tools(tools : Array(Provider::LanguageModel::Tool) | Nil, tool_choice : Provider::LanguageModel::ToolChoice | Nil = nil) : PrepareToolsResult

  Prepares tools for OpenAI chat completions API.

• .transcription_response_format_for_model(model_id : String) : String

  Returns the appropriate response format for a model.

• .valid_speech_format?(format : String) : Bool

  Validates if a format is supported for speech generation.

Class Method Detail

# Using environment variable OPENAI_API_KEY
provider = AI::OpenAI.create_openai

# With explicit API key
provider = AI::OpenAI.create_openai(api_key: "sk-...")

# With custom base URL (for proxies or Azure OpenAI)
provider = AI::OpenAI.create_openai(
  base_url: "https://my-proxy.example.com/v1",
  api_key: "sk-..."
)

# With organization and project
provider = AI::OpenAI.create_openai(
  api_key: "sk-...",
  organization: "org-...",
  project: "proj_..."
)

model = AI::OpenAI.openai.chat("gpt-4o")