ark

type APIType string

type BatchChatConfig struct {
	// EnableBatchChat specifies whether to use the batch chat completion API. Only applies to non-streaming scenarios.
	// For authentication details, see: https://www.volcengine.com/docs/82379/1399517?lang=en#01826852
	EnableBatchChat bool `json:"enable_batch_chat,omitempty"`

	// BatchChatTimeout specifies the timeout for the batch chat completion API. When using batch chat model must set a timeout period.
	// Model will keep retrying until the timeout or the execution succeeds. It is using context timeout to implement the retry time limit.
	// Attention: BatchChatAsyncRetryTimeout is different from the http client timeout which controls the timeout for a single HTTP request.
	// Required. Recommend to set a longer timeout period.
	BatchChatAsyncRetryTimeout time.Duration `json:"batch_chat_async_retry_timeout,omitempty"`

	// BatchMaxParallel specifies the maximum number of parallel requests to send to the chat completion API.
	// Optional. Default: 3000.
	BatchMaxParallel *int `json:"batch_max_parallel,omitempty"`
}

type CacheConfig struct {
	// APIType controls which API the cache uses to make calls.
	// Note that if the type is ResponsesAPI,
	// the following configuration will not be available (ARK may support it in the future):
	// `Region`, `AccessKey`, `SecretKey`, `Stop`, `FrequencyPenalty`, `LogitBias`, `PresencePenalty`,
	// `LogProbs`, `TopLogProbs`.
	// It can be overridden by [WithCache].
	// Optional. Default: ContextAPI.
	//
	// Deprecated: This field defaults to ContextAPI. To use the ResponsesAPI, use NewResponsesAPIChatModel to create a ResponsesAPIChatModel instead of setting APIType to ResponsesAPI.
	APIType *APIType `json:"api_type,omitempty"`

	// SessionCache is the configuration of ResponsesAPI session cache.
	// It can be overridden by [WithCache].
	// Optional.
	SessionCache *SessionCacheConfig `json:"session_cache,omitempty"`
}

type CacheInfo struct {
	// ContextID return by ContextAPI, it's specifies the id of prefix that can be used with [WithCache.ContextID] option.
	ContextID string
	// ResponseID return by ResponsesAPI, it's specifies the id of prefix that can be used with [WithCache.HeadPreviousResponseID] option.
	ResponseID string
	// Usage specifies the token usage of prefix
	Usage schema.TokenUsage
}

type CacheOption struct {
	// APIType specifies the API type for caching.
	// Deprecated: This field defaults to ContextAPI and will be removed in a future version.
	// To use the ResponsesAPI, please use NewResponsesAPIChatModel to create a ResponsesAPIChatModel.
	APIType APIType

	// ContextID is the unique identifier returned by ContextAPI.
	// Note: This field is only applicable when using ContextAPI.
	// Important: ContextID will not be compatible with response ID from ResponsesAPI in future releases.
	// For prefix caching with ResponsesAPI, use HeadPreviousResponseID instead.
	// For session caching with ResponsesAPI, use SessionCache instead.
	// Optional.
	ContextID *string

	// HeadPreviousResponseID is a response ID from a previous ResponsesAPI call.
	// This ID links the current request to a previous conversation context, enabling
	// features like conversation continuation and prefix caching.
	// The referenced response must be cached before use.
	// Only applicable for ResponsesAPI.
	// Optional.
	HeadPreviousResponseID *string

	// SessionCache is the configuration of ResponsesAPI session cache.
	// Optional.
	SessionCache *SessionCacheConfig
}

type ChatModel struct {
	// contains filtered or unexported fields
}

type ChatModelConfig struct {
	// Timeout specifies the maximum duration to wait for API responses
	// If HTTPClient is set, Timeout will not be used.
	// Optional. Default: 10 minutes
	Timeout *time.Duration `json:"timeout"`

	// HTTPClient specifies the client to send HTTP requests.
	// If HTTPClient is set, Timeout will not be used.
	// Optional. Default &http.Client{Timeout: Timeout}
	HTTPClient *http.Client `json:"http_client"`

	// RetryTimes specifies the number of retry attempts for failed API calls
	// Optional. Default: 2
	RetryTimes *int `json:"retry_times"`

	// BaseURL specifies the base URL for Ark service
	// Optional. Default: "https://ark.cn-beijing.volces.com/api/v3"
	BaseURL string `json:"base_url"`

	// Region specifies the region where Ark service is located
	// Optional. Default: "cn-beijing"
	Region string `json:"region"`

	// The following three fields are about authentication - either APIKey or AccessKey/SecretKey pair is required
	// For authentication details, see: https://www.volcengine.com/docs/82379/1298459
	// APIKey takes precedence if both are provided
	APIKey string `json:"api_key"`

	AccessKey string `json:"access_key"`

	SecretKey string `json:"secret_key"`

	// Model specifies the ID of endpoint on ark platform
	// Required
	Model string `json:"model"`

	// MaxTokens limits the maximum number of output tokens in the Chat Completion API. See https://www.volcengine.com/docs/82379/1494384.
	// In Responses API, corresponds to `max_output_tokens`, representing both the model output and reasoning output. See https://www.volcengine.com/docs/82379/1569618.
	// Optional. In chat completion, default: 4096, in Responses API, no default.
	MaxTokens *int `json:"max_tokens,omitempty"`

	// MaxCompletionTokens specifies the maximum tokens in the Chat Completion API,
	// representing both the model output and reasoning output. See https://www.volcengine.com/docs/82379/1569618.
	// Range: 0 to 65,536 tokens. Exceeding the maximum threshold will result in an error.
	// Note: In chat completion, MaxCompletionTokens and MaxTokens cannot both be set, in Responses API, this field is ignored; use MaxTokens.
	// Optional.
	MaxCompletionTokens *int `json:"max_completion_tokens,omitempty"`

	// Temperature specifies what sampling temperature to use
	// Generally recommend altering this or TopP but not both
	// Range: 0.0 to 1.0. Higher values make output more random
	// Optional. Default: 1.0
	Temperature *float32 `json:"temperature,omitempty"`

	// TopP controls diversity via nucleus sampling
	// Generally recommend altering this or Temperature but not both
	// Range: 0.0 to 1.0. Lower values make output more focused
	// Optional. Default: 0.7
	TopP *float32 `json:"top_p,omitempty"`

	// Stop sequences where the API will stop generating further tokens
	// Optional. Example: []string{"\n", "User:"}
	Stop []string `json:"stop,omitempty"`

	// FrequencyPenalty prevents repetition by penalizing tokens based on frequency
	// Range: -2.0 to 2.0. Positive values decrease likelihood of repetition
	// Optional. Default: 0
	FrequencyPenalty *float32 `json:"frequency_penalty,omitempty"`

	// LogitBias modifies likelihood of specific tokens appearing in completion
	// Optional. Map token IDs to bias values from -100 to 100
	LogitBias map[string]int `json:"logit_bias,omitempty"`

	// PresencePenalty prevents repetition by penalizing tokens based on presence
	// Range: -2.0 to 2.0. Positive values increase likelihood of new topics
	// Optional. Default: 0
	PresencePenalty *float32 `json:"presence_penalty,omitempty"`

	// CustomHeader the http header passed to model when requesting model
	CustomHeader map[string]string `json:"custom_header"`

	// LogProbs specifies whether to return log probabilities of the output tokens.
	LogProbs bool `json:"log_probs"`

	// TopLogProbs specifies the number of most likely tokens to return at each token position, each with an associated log probability.
	TopLogProbs int `json:"top_log_probs"`

	// ResponseFormat specifies the format that the model must output.
	ResponseFormat *ResponseFormat `json:"response_format,omitempty"`

	// Thinking controls whether the model is set to activate the deep thinking mode.
	// It is set to be enabled by default.
	Thinking *model.Thinking `json:"thinking,omitempty"`

	// ServiceTier specifies whether to use the TPM guarantee package. The effective target has purchased the inference access point for the guarantee package.
	ServiceTier *string `json:"service_tier"`

	// ReasoningEffort specifies the reasoning effort of the model.
	// Optional.
	ReasoningEffort *model.ReasoningEffort `json:"reasoning_effort,omitempty"`

	// BatchChat ark batch chat config
	// Optional.
	BatchChat *BatchChatConfig `json:"batch_chat,omitempty"`

	Cache *CacheConfig `json:"cache,omitempty"`
}

type ImageGenerationConfig struct {
	// For authentication, APIKey is required as the image generation API only supports API Key authentication.
	// For authentication details, see: https://www.volcengine.com/docs/82379/1298459
	// Required
	APIKey string `json:"api_key"`

	// Model specifies the ID of endpoint on ark platform
	// Required
	Model string `json:"model"`

	// Timeout specifies the maximum duration to wait for API responses
	// If HTTPClient is set, Timeout will not be used.
	// Optional. Default: 10 minutes
	Timeout *time.Duration `json:"timeout"`

	// HTTPClient specifies the client to send HTTP requests.
	// If HTTPClient is set, Timeout will not be used.
	// Optional. Default &http.Client{Timeout: Timeout}
	HTTPClient *http.Client `json:"http_client"`

	// RetryTimes specifies the number of retry attempts for failed API calls
	// Optional. Default: 2
	RetryTimes *int `json:"retry_times"`

	// BaseURL specifies the base URL for Ark service
	// Optional. Default: "https://ark.cn-beijing.volces.com/api/v3"
	BaseURL string `json:"base_url"`

	// Region specifies the region where Ark service is located
	// Optional. Default: "cn-beijing"
	Region string `json:"region"`

	// Size specifies the dimensions of the generated image.
	// It can be a resolution keyword (e.g., "1K", "2K", "4K") or a custom resolution
	// in "{width}x{height}" format (e.g., "1920x1080").
	// When using custom resolutions, the total pixels must be between 1280x720 and 4096x4096,
	// and the aspect ratio (width/height) must be between 1/16 and 16.
	// Optional. Defaults to "2048x2048".
	Size string `json:"size"`

	// SequentialImageGeneration determines if the model should generate a sequence of images.
	// Possible values:
	//  - "auto": The model decides whether to generate multiple images based on the prompt.
	//  - "disabled": Only a single image is generated.
	// Optional. Defaults to "disabled".
	SequentialImageGeneration SequentialImageGeneration `json:"sequential_image_generation"`

	// SequentialImageGenerationOption sets the maximum number of images to generate when
	// SequentialImageGeneration is set to "auto".
	// The value must be between 1 and 15.
	// Optional. Defaults to 15.
	SequentialImageGenerationOption *model.SequentialImageGenerationOptions `json:"sequential_image_generation_option"`

	// ResponseFormat specifies how the generated image data is returned.
	// Possible values:
	//  - "url": A temporary URL to download the image (valid for 24 hours).
	//  - "b64_json": The image data encoded as a Base64 string in the response.
	// Optional. Defaults to "url".
	ResponseFormat ImageResponseFormat `json:"response_format"`

	// DisableWatermark, if set to true, removes the "AI Generated" watermark
	// from the bottom-right corner of the image.
	// Optional. Defaults to false.
	DisableWatermark bool `json:"disable_watermark"`
}

type ImageGenerationModel struct {
	// contains filtered or unexported fields
}

type ImageResponseFormat string

type ReasoningEffort = arkModel.ReasoningEffort

type ResponseFormat struct {
	Type       model.ResponseFormatType                       `json:"type"`
	JSONSchema *model.ResponseFormatJSONSchemaJSONSchemaParam `json:"json_schema,omitempty"`
}

type ResponsesAPIChatModel struct {
	// contains filtered or unexported fields
}

type ResponsesAPIConfig struct {
	// Timeout specifies the timeout for the HTTP client making requests to the ResponsesAPI.
	// If HTTPClient is set, Timeout will not be used.
	// Optional. Default: 10 minutes
	Timeout *time.Duration `json:"timeout"`

	// HTTPClient specifies the client to send HTTP requests.
	// If HTTPClient is set, Timeout will not be used.
	// Optional. Default &http.Client{Timeout: Timeout}
	HTTPClient *http.Client `json:"http_client"`

	// RetryTimes specifies the number of retry attempts for failed API calls
	// Optional. Default: 2
	RetryTimes *int `json:"retry_times"`

	// BaseURL specifies the base URL for Ark service
	// Optional. Default: "https://ark.cn-beijing.volces.com/api/v3"
	BaseURL string `json:"base_url"`

	// Region specifies the region where Ark service is located
	// Optional. Default: "cn-beijing"
	Region string `json:"region"`

	// The following three fields are about authentication - either APIKey or AccessKey/SecretKey pair is required
	// For authentication details, see: https://www.volcengine.com/docs/82379/1298459
	// APIKey takes precedence if both are provided
	APIKey string `json:"api_key"`

	AccessKey string `json:"access_key"`

	SecretKey string `json:"secret_key"`

	// Model specifies the ID of endpoint on ark platform
	// Required
	Model string `json:"model"`

	// MaxOutputTokens specifies the maximum number of tokens for model output, including both model responses and thought chain content.
	// Optional.
	MaxOutputTokens *int `json:"max_output_tokens,omitempty"`

	// Temperature specifies what sampling temperature to use
	// Generally recommend altering this or TopP but not both
	// Range: 0.0 to 2.0. Higher values make output more random
	// Optional. Default: 1.0
	Temperature *float32 `json:"temperature,omitempty"`

	// TopP controls diversity via nucleus sampling
	// Generally recommend altering this or Temperature but not both
	// Range: 0.0 to 1.0. Lower values make output more focused
	// Optional. Default: 0.7
	TopP *float32 `json:"top_p,omitempty"`

	// CustomHeader the http header passed to model when requesting model
	// Optional.
	CustomHeader map[string]string `json:"custom_header"`

	// ResponseFormat specifies the format that the model must output.
	// Optional.
	ResponseFormat *ResponseFormat `json:"response_format,omitempty"`

	// Thinking controls whether the model is set to activate the deep thinking mode.
	// It is set to be enabled by default.
	// Optional.
	Thinking *Thinking `json:"thinking,omitempty"`

	// ServiceTier specifies whether to use the TPM guarantee package. The effective target has purchased the inference access point for the guarantee package.
	// Optional.
	ServiceTier *string `json:"service_tier"`

	// ReasoningEffort specifies the reasoning effort of the model.
	// Optional.
	ReasoningEffort *ReasoningEffort `json:"reasoning_effort,omitempty"`

	// SessionCache is the configuration of ResponsesAPI session cache.
	// It can be overridden by [WithCache].
	// Optional.
	SessionCache *SessionCacheConfig `json:"session_cache,omitempty"`

	// EnableToolWebSearch enables the web search tool.
	// Web Search is a basic internet search tool that can obtain real-time public network information
	// (such as news, products, weather, etc.) for your large model through the Responses API.
	// This tool can solve core issues such as data timeliness, knowledge gaps, and information synchronization,
	// and you do not need to develop your own search engine or maintain data resources.
	// Note: This option is only effective for the Responses API.
	// For more details, see https://www.volcengine.com/docs/82379/1756990?lang=zh
	// Optional.
	EnableToolWebSearch *ToolWebSearch `json:"enable_tool_web_search,omitempty"`

	// MaxToolCalls specifies the maximum number of tool-calling rounds.
	// The value must be in the range [1, 10].
	// After this limit is reached, the model is prompted to stop making further tool calls and generate a response.
	// Note: This is a best-effort parameter, and the actual number of calls may be affected by model performance and tool results.
	// The default value for the Web Search tool is 3.
	// For more details, see https://www.volcengine.com/docs/82379/1569618?lang=zh
	// Optional.
	MaxToolCalls *int64 `json:"max_tool_calls,omitempty"`

	// EnableReasoningContentPassback controls whether reasoning content
	// from assistant messages is passed back to the model in multi-turn conversations.
	// When enabled, reasoning summaries and raw reasoning content are passed back in their original form,
	// allowing the model to be aware of its prior chain-of-thought.
	// However, if a valid previous_response_id is set (via session cache), the passback is
	// automatically skipped because previous_response_id already preserves the full conversation
	// context including the chain-of-thought on the server side.
	// Note: This feature requires doubao models v1.8+. Earlier versions (e.g., v1.6) do not
	// support reasoning items in the input and will return an error.
	// For more details, see https://www.volcengine.com/docs/82379/1449737
	// Default: false.
	// Optional.
	EnableReasoningContentPassback bool `json:"enable_reasoning_content_passback,omitempty"`
}

type SequentialImageGeneration string

type SessionCacheConfig struct {
	// EnableCache controls whether session caching is active.
	// When enabled, the model stores both inputs and responses for each conversation turn,
	// allowing them to be retrieved later via API.
	// Response IDs are saved in output messages and can be accessed using GetResponseID.
	// For multi-turn conversations, the ARK ChatModel automatically identifies the most recent
	// cached message from all inputs and passes its response ID to model to maintain context continuity.
	// This message and all previous ones are trimmed before being sent to the model.
	// When both HeadPreviousResponseID and cached message exist, the message's response ID takes precedence.
	// Use InvalidateMessageCaches to disables caching for the specified messages.
	EnableCache bool `json:"enable_cache"`

	// TTL specifies the survival time of cached data in seconds, with a maximum of 3 * 86400(3 days).
	TTL int `json:"ttl"`
}

type Source string

type Thinking = arkModel.Thinking

type ThinkingType = arkModel.ThinkingType

type ToolWebSearch struct {
	// Limit is the maximum number of results to retrieve per search in a single round.
	// It affects input size and performance. The value must be in the range [1, 50].
	// Optional. Default 10
	Limit *int64 `json:"limit,omitempty"`

	// UserLocation is the user's geographical location, used for scenarios like weather queries.
	// It includes `type`, `country`, `city`, and `region` fields.
	UserLocation *UserLocation `json:"user_location,omitempty"`

	// Sources is a list of additional content sources for web searches. See the Source type for available options.
	Sources []Source `json:"sources,omitempty"`

	// MaxKeyword is the maximum number of keywords to search in parallel within a single tool-use round.
	// For example, if the model identifies multiple keywords to search (e.g., "A", "B", "C")
	// and max_keyword is 1, only the first keyword ("A") will be searched.
	// The value must be in the range [1, 50].
	// Optional.
	MaxKeyword *int32 `json:"max_keyword,omitempty"`
}

type UserLocation struct {
	City     *string `json:"city,omitempty"`
	Country  *string `json:"country,omitempty"`
	Region   *string `json:"region,omitempty"`
	Timezone *string `json:"timezone,omitempty"`
}