Module Chatoyant_provider.XaiSource

Standalone xAI API mirror.

xAI shares OpenAI-compatible wire formats for some endpoints, but this module owns xAI semantics directly: model capability quirks, web search, cost ticks, Imagine image/video endpoints, and xAI-specific errors.

Sourcetype role =
  1. | System
  2. | User
  3. | Assistant
  4. | Tool
Sourcetype message = {
  1. message_role : role;
  2. message_content : string option;
  3. message_name : string option;
  4. message_tool_call_id : string option;
  5. message_tool_calls : Provider.tool_call list;
}
Sourcetype tool =
  1. | Function of Openai.function_tool
  2. | Raw_tool of Chatoyant_runtime.Json.t
Sourcetype tool_choice =
  1. | Auto
  2. | None_
  3. | Required
  4. | Tool of string
  5. | Raw_tool_choice of Chatoyant_runtime.Json.t
Sourcetype service_tier =
  1. | Auto_tier
  2. | Default_tier
  3. | Priority_tier
  4. | Service_tier of string
Sourcetype response_format =
  1. | Text
  2. | Json_object
  3. | Json_schema of {
    1. schema_name : string;
    2. schema_description : string option;
    3. schema_value : Chatoyant_runtime.Json.t;
    4. schema_strict : bool;
    }
Sourcetype chat_request = {
  1. chat_model : string;
  2. chat_messages : message list;
  3. chat_stream : bool;
  4. chat_temperature : float option;
  5. chat_max_tokens : int option;
  6. chat_top_p : float option;
  7. chat_stop : string list;
  8. chat_user : string option;
  9. chat_seed : int option;
  10. chat_logprobs : bool option;
  11. chat_top_logprobs : int option;
  12. chat_n : int option;
  13. chat_response_format : response_format option;
  14. chat_tools : tool list;
  15. chat_tool_choice : tool_choice option;
  16. chat_parallel_tool_calls : bool option;
  17. chat_extra : (string * Chatoyant_runtime.Json.t) list;
}

Chat Completions request body for xAI's /v1/chat/completions endpoint. Optional fields intentionally stay explicit instead of being inherited from OpenAI, because xAI evolves capabilities and unsupported parameters on its own schedule. chat_extra is the forward-compatible escape hatch for freshly shipped provider fields.

Sourcetype chat_response = {
  1. response_id : string option;
  2. response_model : string option;
  3. response_content : string;
  4. response_reasoning_content : string;
  5. response_usage : Chatoyant_tokens.Cost.usage;
  6. response_raw : Chatoyant_runtime.Json.t;
}

Decoded chat response. response_raw preserves the complete provider JSON so parity tests can inspect unknown fields without weakening the typed normalized surface.

Sourcetype responses_input =
  1. | Responses_text of string
  2. | Responses_items of Chatoyant_runtime.Json.t list
Sourcetype responses_request = {
  1. responses_model : string;
  2. responses_input : responses_input;
  3. responses_instructions : string option;
  4. responses_previous_response_id : string option;
  5. responses_store : bool option;
  6. responses_stream : bool;
  7. responses_temperature : float option;
  8. responses_top_p : float option;
  9. responses_max_output_tokens : int option;
  10. responses_tools : tool list;
  11. responses_tool_choice : tool_choice option;
  12. responses_text_format : response_format option;
  13. responses_parallel_tool_calls : bool option;
  14. responses_top_logprobs : int option;
  15. responses_truncation : string option;
  16. responses_extra : (string * Chatoyant_runtime.Json.t) list;
}

Preferred xAI Responses API request body for /v1/responses.

Sourcetype response_status =
  1. | Completed
  2. | In_progress
  3. | Incomplete
  4. | Failed_response
  5. | Unknown_response_status of string
Sourcetype responses_response = {
  1. responses_id : string option;
  2. responses_model : string option;
  3. responses_status : response_status;
  4. responses_output_text : string;
  5. responses_reasoning_text : string;
  6. responses_usage : Chatoyant_tokens.Cost.usage;
  7. responses_raw : Chatoyant_runtime.Json.t;
}

Decoded Responses API object, including message output text and reasoning summary text when xAI returns it.

Sourcetype delete_response = {
  1. deleted_id : string option;
  2. deleted : bool;
  3. deleted_raw : Chatoyant_runtime.Json.t;
}
Sourcetype model = {
  1. model_id : string option;
  2. model_object : string option;
  3. model_owned_by : string option;
  4. model_created : int option;
  5. model_raw : Chatoyant_runtime.Json.t;
}
Sourcetype model_list = {
  1. models : model list;
  2. models_raw : Chatoyant_runtime.Json.t;
}
Sourcetype upload_part = {
  1. upload_filename : string;
  2. upload_content_type : string option;
  3. upload_body : string;
}
Sourcetype form_part = {
  1. form_name : string;
  2. form_filename : string option;
  3. form_content_type : string option;
  4. form_body : string;
}
Sourcetype file_upload = {
  1. file_filename : string;
  2. file_content_type : string option;
  3. file_body : string;
  4. file_purpose : string;
  5. file_expires_after : int option;
}
Sourcetype file_object = {
  1. file_id : string option;
  2. file_object : string option;
  3. file_bytes : int option;
  4. file_filename : string option;
  5. file_purpose : string option;
  6. file_created_at : int option;
  7. file_expires_at : string option;
  8. file_raw : Chatoyant_runtime.Json.t;
}
Sourcetype file_list = {
  1. files : file_object list;
  2. pagination_token : string option;
  3. raw : Chatoyant_runtime.Json.t;
}
Sourcetype file_delete = {
  1. deleted_file_id : string option;
  2. deleted : bool;
  3. raw : Chatoyant_runtime.Json.t;
}
Sourcetype batch_create_request = {
  1. batch_name : string;
}
Sourcetype batch = {
  1. batch_id : string option;
  2. batch_create_api_key_id : string option;
  3. batch_create_time : string option;
  4. batch_name : string option;
  5. batch_state : Chatoyant_runtime.Json.t option;
  6. batch_raw : Chatoyant_runtime.Json.t;
}
Sourcetype batch_list = {
  1. batches : batch list;
  2. pagination_token : string option;
  3. raw : Chatoyant_runtime.Json.t;
}
Sourcetype batch_requests_add = {
  1. batch_requests : Chatoyant_runtime.Json.t list;
}
Sourcetype batch_request_metadata_list = {
  1. batch_request_metadata : Chatoyant_runtime.Json.t list;
  2. pagination_token : string option;
  3. raw : Chatoyant_runtime.Json.t;
}
Sourcetype api_error = {
  1. error_type : string option;
  2. error_message : string;
  3. error_raw : Chatoyant_runtime.Json.t option;
}
Sourcetype tts_output_format = {
  1. output_codec : string option;
  2. output_sample_rate : int option;
  3. output_bit_rate : int option;
}
Sourcetype tts_request = {
  1. tts_text : string;
  2. tts_voice_id : string option;
  3. tts_language : string;
  4. tts_output_format : tts_output_format option;
  5. tts_speed : float option;
  6. tts_optimize_streaming_latency : int option;
  7. tts_text_normalization : bool option;
  8. tts_with_timestamps : bool option;
  9. tts_extra : (string * Chatoyant_runtime.Json.t) list;
}

REST text-to-speech request for /v1/tts. The normal response body is raw audio bytes; when tts_with_timestamps is true, xAI returns a JSON envelope as the body.

Sourcetype audio_body = {
  1. audio_body : string;
  2. audio_content_type : string option;
}
Sourcetype stt_request = {
  1. stt_file : upload_part option;
  2. stt_url : string option;
  3. stt_audio_format : string option;
  4. stt_sample_rate : int option;
  5. stt_language : string option;
  6. stt_format : bool option;
  7. stt_multichannel : bool option;
  8. stt_channels : int option;
  9. stt_diarize : bool option;
  10. stt_keyterms : string list;
  11. stt_filler_words : bool option;
  12. stt_extra : (string * string) list;
}

REST speech-to-text request for /v1/stt. Either stt_file or stt_url must be supplied. When stt_file is present it is encoded last, matching xAI's multipart requirement.

Sourcetype stt_word = {
  1. word_text : string option;
  2. word_start : float option;
  3. word_end : float option;
  4. word_speaker : int option;
  5. word_raw : Chatoyant_runtime.Json.t;
}
Sourcetype stt_channel = {
  1. channel_index : int option;
  2. channel_text : string option;
  3. channel_words : stt_word list;
  4. channel_raw : Chatoyant_runtime.Json.t;
}
Sourcetype stt_response = {
  1. stt_text : string option;
  2. stt_language : string option;
  3. stt_duration : float option;
  4. stt_words : stt_word list;
  5. stt_channels : stt_channel list;
  6. stt_raw : Chatoyant_runtime.Json.t;
}
Sourcetype voice = {
  1. voice_id : string option;
  2. voice_name : string option;
  3. voice_description : string option;
  4. voice_gender : string option;
  5. voice_accent : string option;
  6. voice_age : string option;
  7. voice_language : string option;
  8. voice_use_case : string option;
  9. voice_tone : string option;
  10. voice_created_at : string option;
  11. voice_raw : Chatoyant_runtime.Json.t;
}
Sourcetype voice_list = {
  1. voices : voice list;
  2. voices_pagination_token : string option;
  3. voices_raw : Chatoyant_runtime.Json.t;
}
Sourcetype custom_voice_request = {
  1. custom_voice_file : upload_part;
  2. custom_voice_name : string option;
  3. custom_voice_description : string option;
  4. custom_voice_gender : string option;
  5. custom_voice_accent : string option;
  6. custom_voice_age : string option;
  7. custom_voice_language : string option;
  8. custom_voice_use_case : string option;
  9. custom_voice_tone : string option;
  10. custom_voice_extra : (string * string) list;
}
Sourcetype custom_voice_update = {
  1. custom_voice_update_name : string option;
  2. custom_voice_update_description : string option;
  3. custom_voice_update_gender : string option;
  4. custom_voice_update_accent : string option;
  5. custom_voice_update_age : string option;
  6. custom_voice_update_language : string option;
  7. custom_voice_update_use_case : string option;
  8. custom_voice_update_tone : string option;
  9. custom_voice_update_extra : (string * Chatoyant_runtime.Json.t) list;
}
Sourcetype voice_delete = {
  1. deleted_voice_id : string option;
  2. voice_deleted : bool;
  3. voice_delete_raw : Chatoyant_runtime.Json.t;
}
Sourcetype realtime_client_secret_request = {
  1. realtime_client_secret_expires_after_seconds : int option;
  2. realtime_client_secret_extra : (string * Chatoyant_runtime.Json.t) list;
}

Ephemeral token request for browser/mobile WebSocket clients.

Sourcetype realtime_client_secret = {
  1. realtime_client_secret_value : string option;
  2. realtime_client_secret_expires_at : int option;
  3. realtime_client_secret_raw : Chatoyant_runtime.Json.t;
}

Ephemeral Realtime client secret returned by xAI.

Sourcetype websocket_config = {
  1. websocket_api_key : string;
  2. websocket_url : string;
  3. websocket_timeout_ms : int option;
  4. websocket_headers : (string * string) list;
  5. websocket_protocols : string list;
}

xAI WebSocket config for voice-agent realtime and streaming TTS.

Sourcetype responses_stream_event =
  1. | Response_created of responses_response
  2. | Response_in_progress of responses_response
  3. | Response_completed of responses_response
  4. | Response_failed of responses_response
  5. | Response_incomplete of responses_response
  6. | Response_output_text_delta of {
    1. item_id : string option;
    2. output_index : int option;
    3. content_index : int option;
    4. delta : string;
    }
  7. | Response_output_text_done of {
    1. item_id : string option;
    2. output_index : int option;
    3. content_index : int option;
    4. text : string;
    }
  8. | Response_reasoning_summary_text_delta of {
    1. item_id : string option;
    2. output_index : int option;
    3. summary_index : int option;
    4. delta : string;
    }
  9. | Response_function_call_arguments_delta of {
    1. item_id : string option;
    2. output_index : int option;
    3. delta : string;
    }
  10. | Response_function_call_arguments_done of {
    1. item_id : string option;
    2. output_index : int option;
    3. arguments : string;
    }
  11. | Response_refusal_delta of string
  12. | Response_error of api_error
  13. | Response_raw_event of {
    1. event_type : string option;
    2. raw : Chatoyant_runtime.Json.t;
    }
    (*

    xAI Responses SSE events. The provider currently follows OpenAI's event names for /v1/responses, while this type remains owned by the xAI module so downstream explicit-provider code never depends on OpenAI internals.

    *)
Sourcetype image_response_format =
  1. | Url
  2. | Base64_json
Sourcetype image_request = {
  1. image_model : string option;
  2. image_prompt : string;
  3. image_n : int option;
  4. image_response_format : image_response_format option;
  5. image_aspect_ratio : string option;
  6. image_resolution : string option;
  7. image_user : string option;
  8. image_extra : (string * Chatoyant_runtime.Json.t) list;
}

Image generation request for Grok Imagine image models.

Sourcetype image_edit_source = {
  1. source_url : string;
  2. source_type : string;
}
Sourcetype image_edit_request = {
  1. edit_model : string option;
  2. edit_prompt : string;
  3. edit_images : image_edit_source list;
  4. edit_n : int option;
  5. edit_response_format : image_response_format option;
  6. edit_aspect_ratio : string option;
  7. edit_resolution : string option;
  8. edit_extra : (string * Chatoyant_runtime.Json.t) list;
}

Image edit request. The source list is encoded as the singular xAI image field, either as one object or an array of reference images.

Sourcetype image_data = {
  1. image_url : string option;
  2. image_b64_json : string option;
  3. image_revised_prompt : string option;
}
Sourcetype image_response = {
  1. image_created : int option;
  2. image_model : string option;
  3. image_data : image_data list;
  4. image_raw : Chatoyant_runtime.Json.t;
}
Sourcetype video_request = {
  1. video_model : string option;
  2. video_prompt : string;
  3. video_duration : int option;
  4. video_aspect_ratio : string option;
  5. video_resolution : string option;
  6. video_image_url : string option;
  7. video_url : string option;
  8. video_extra : (string * Chatoyant_runtime.Json.t) list;
}

Async Imagine video generation/edit request. Poll the returned request id with Make_client.get_video_status.

Sourcetype video_start_response = {
  1. request_id : string;
  2. raw : Chatoyant_runtime.Json.t;
}
Sourcetype video_status =
  1. | Queued
  2. | Processing
  3. | Done
  4. | Failed
  5. | Expired
  6. | Unknown_status of string
Sourcetype video_status_response = {
  1. status : video_status;
  2. video_url : string option;
  3. video_duration : int option;
  4. video_model : string option;
  5. raw : Chatoyant_runtime.Json.t;
}
Sourcetype collection_request = {
  1. collection_name : string;
  2. collection_description : string option;
  3. collection_index_configuration : Chatoyant_runtime.Json.t option;
  4. collection_field_definitions : Chatoyant_runtime.Json.t list;
  5. collection_extra : (string * Chatoyant_runtime.Json.t) list;
}
Sourcetype collection_update = {
  1. collection_update_name : string option;
  2. collection_update_description : string option;
  3. collection_update_index_configuration : Chatoyant_runtime.Json.t option;
  4. collection_update_field_definitions : Chatoyant_runtime.Json.t list;
  5. collection_update_extra : (string * Chatoyant_runtime.Json.t) list;
}
Sourcetype collection = {
  1. collection_id : string option;
  2. collection_name : string option;
  3. collection_description : string option;
  4. collection_created_at : string option;
  5. collection_documents_count : int option;
  6. collection_index_configuration : Chatoyant_runtime.Json.t option;
  7. collection_field_definitions : Chatoyant_runtime.Json.t option;
  8. collection_raw : Chatoyant_runtime.Json.t;
}
Sourcetype collection_list = {
  1. collections : collection list;
  2. collections_pagination_token : string option;
  3. collections_raw : Chatoyant_runtime.Json.t;
}
Sourcetype collection_document = {
  1. document_file_metadata : Chatoyant_runtime.Json.t option;
  2. document_status : string option;
  3. document_error_message : string option;
  4. document_last_indexed_at : string option;
  5. document_fields : Chatoyant_runtime.Json.t option;
  6. document_raw : Chatoyant_runtime.Json.t;
}
Sourcetype collection_document_list = {
  1. collection_documents : collection_document list;
  2. collection_documents_pagination_token : string option;
  3. collection_documents_raw : Chatoyant_runtime.Json.t;
}
Sourcetype collection_delete = {
  1. collection_delete_id : string option;
  2. collection_deleted : bool;
  3. collection_delete_raw : Chatoyant_runtime.Json.t;
}
Sourcetype collection_search_request = {
  1. collection_search_query : string;
  2. collection_search_limit : int option;
  3. collection_search_filter : string option;
  4. collection_search_extra : (string * Chatoyant_runtime.Json.t) list;
}
Sourcetype collection_search_response = {
  1. collection_search_results : Chatoyant_runtime.Json.t list;
  2. collection_search_raw : Chatoyant_runtime.Json.t;
}
Sourceval role_to_string : role -> string
Sourceval service_tier_to_string : service_tier -> string
Sourceval service_tier_extra : service_tier -> string * Chatoyant_runtime.Json.t
Sourceval background_extra : bool -> string * Chatoyant_runtime.Json.t
Sourceval stt_request_parts : stt_request -> form_part list
Sourceval custom_voice_request_parts : custom_voice_request -> form_part list
Sourceval custom_voice_update_json : custom_voice_update -> Chatoyant_runtime.Json.t
Sourceval realtime_client_secret_request_json : realtime_client_secret_request -> Chatoyant_runtime.Json.t
Sourceval chat_request_json : chat_request -> Chatoyant_runtime.Json.t
Sourceval responses_request_json : responses_request -> Chatoyant_runtime.Json.t
Sourceval batch_create_request_json : batch_create_request -> Chatoyant_runtime.Json.t
Sourceval batch_requests_add_json : batch_requests_add -> Chatoyant_runtime.Json.t
Sourceval collection_request_json : collection_request -> Chatoyant_runtime.Json.t
Sourceval collection_update_json : collection_update -> Chatoyant_runtime.Json.t
Sourceval collection_search_request_json : collection_search_request -> Chatoyant_runtime.Json.t
Sourceval image_request_json : image_request -> Chatoyant_runtime.Json.t
Sourceval image_edit_request_json : image_edit_request -> Chatoyant_runtime.Json.t
Sourceval video_request_json : video_request -> Chatoyant_runtime.Json.t
Sourceval authorization_headers : api_key:string -> (string * string) list

Bearer auth headers for xAI REST calls.

Sourceval voice_agent_url : ?base_url:string -> model:string -> unit -> string
Sourceval streaming_tts_url : ?base_url:string -> ?language:string -> ?voice:string -> ?codec:string -> ?sample_rate:int -> ?bit_rate:int -> ?speed:float -> ?optimize_streaming_latency:int -> ?text_normalization:bool -> ?with_timestamps:bool -> unit -> string
Sourceval streaming_stt_url : ?base_url:string -> ?sample_rate:int -> ?encoding:string -> ?interim_results:bool -> ?endpointing:int -> ?language:string -> ?diarize:bool -> ?filler_words:bool -> ?multichannel:bool -> ?channels:int -> ?keyterms:string list -> ?smart_turn:float -> ?smart_turn_timeout:int -> unit -> string
Sourceval responses_websocket_url : ?base_url:string -> unit -> string
Sourceval chat_response_of_json : Chatoyant_runtime.Json.t -> chat_response
Sourceval generation_of_chat_response : chat_response -> Provider.generation
Sourceval responses_response_of_json : Chatoyant_runtime.Json.t -> responses_response
Sourceval generation_of_responses_response : responses_response -> Provider.generation
Sourceval stt_response_of_json : Chatoyant_runtime.Json.t -> stt_response
Sourceval voice_of_json : Chatoyant_runtime.Json.t -> voice
Sourceval voice_list_of_json : Chatoyant_runtime.Json.t -> voice_list
Sourceval voice_delete_of_json : Chatoyant_runtime.Json.t -> voice_delete
Sourceval realtime_client_secret_of_json : Chatoyant_runtime.Json.t -> realtime_client_secret
Sourceval responses_stream_event_of_json : Chatoyant_runtime.Json.t -> responses_stream_event
Sourceval responses_stream_events_of_chunks : string list -> (responses_stream_event list, string) result
Sourceval response_of_stream_chunks : string list -> (responses_response, string) result
Sourceval delete_response_of_json : Chatoyant_runtime.Json.t -> delete_response
Sourceval model_list_of_json : Chatoyant_runtime.Json.t -> model_list
Sourceval file_object_of_json : Chatoyant_runtime.Json.t -> file_object
Sourceval file_list_of_json : Chatoyant_runtime.Json.t -> file_list
Sourceval file_delete_of_json : Chatoyant_runtime.Json.t -> file_delete
Sourceval batch_of_json : Chatoyant_runtime.Json.t -> batch
Sourceval batch_list_of_json : Chatoyant_runtime.Json.t -> batch_list
Sourceval batch_request_metadata_list_of_json : Chatoyant_runtime.Json.t -> batch_request_metadata_list
Sourceval api_error_of_json : Chatoyant_runtime.Json.t -> api_error
Sourceval stream_response_of_chunks : string list -> (chat_response, string) result

Decode OpenAI-compatible SSE chunks while preserving xAI reasoning deltas and cost-tick usage when present.

Sourceval image_response_of_json : Chatoyant_runtime.Json.t -> image_response
Sourceval video_start_response_of_json : Chatoyant_runtime.Json.t -> video_start_response
Sourceval video_status_response_of_json : Chatoyant_runtime.Json.t -> video_status_response
Sourceval collection_of_json : Chatoyant_runtime.Json.t -> collection
Sourceval collection_list_of_json : Chatoyant_runtime.Json.t -> collection_list
Sourceval collection_document_of_json : Chatoyant_runtime.Json.t -> collection_document
Sourceval collection_document_list_of_json : Chatoyant_runtime.Json.t -> collection_document_list
Sourceval collection_delete_of_json : Chatoyant_runtime.Json.t -> collection_delete
Sourceval collection_search_response_of_json : Chatoyant_runtime.Json.t -> collection_search_response

Runtime-independent xAI client. Native OCaml, Node/Melange, browser, and tests supply the HTTP effect implementation; the provider logic never performs ambient IO.

xAI WebSocket helper for Voice Agent and streaming TTS endpoints.

Unified chat adapter used by higher-level Chatoyant core flows.