mistralai

package module
v0.17.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 10, 2026 License: MIT Imports: 20 Imported by: 0

README

mistralai-go

Synchronous Go client for the Mistral API. Each call blocks until Mistral returns HTTP 200 with the full JSON body (no job polling or background workers).

API surface

Method HTTP Use when
OCR POST /v1/files, then POST /v1/ocr Document OCR via file upload (auto-deletes the file afterwards)
OCRByFileID POST /v1/ocr OCR an already-uploaded file by id (no auto-delete)
OCRByURL POST /v1/ocr OCR a document or image referenced by URL (document_url / image_url, incl. data: URIs) — no upload round-trip
Chat POST /v1/chat/completions Single user turn with optional system prompt and output format helpers
ChatCompletion POST /v1/chat/completions Full control: message list, temperature, response_format, etc.
Embeddings POST /v1/embeddings Text embeddings (mistral-embed, batch input, optional dimensions/dtype)
ListModels GET /v1/models List models available to your API key
UploadFile POST /v1/files Upload a file; returns file id
ListFiles GET /v1/files List uploaded files (optional pagination and filters)
DeleteFile DELETE /v1/files/{file_id} Remove an uploaded file
DownloadFile GET /v1/files/{file_id}/content Download raw file content (e.g. batch results)
UploadBatchInput POST /v1/files Build a JSONL input file from typed entries and upload it (purpose=batch)
CreateBatchJob POST /v1/batch/jobs Create an async batch job over an uploaded input file
ListBatchJobs GET /v1/batch/jobs List batch jobs (optional pagination, created_by_me)
GetBatchJob GET /v1/batch/jobs/{job_id} Fetch one batch job
CancelBatchJob POST /v1/batch/jobs/{job_id}/cancel Request cancellation of a batch job

All API calls (including file uploads) retry on 429 and 5xx with jittered exponential backoff, honoring the Retry-After response header (default 4 retries / 5 attempts total, context-aware). Configure with WithMaxRetries; WithMaxRetries(0) disables retries.

Install

go get github.com/kaatinga/mistralai-go

Usage

package main

import (
	"context"
	"bytes"
	"log"
	"net/http"
	"os"
	"time"

	mistralai "github.com/kaatinga/mistralai-go"
)

func main() {
	cl, err := mistralai.NewClient(
		os.Getenv("MISTRAL_API_KEY"),
		mistralai.WithHTTPClient(&http.Client{Timeout: 120 * time.Second}),
	)
	if err != nil {
		log.Fatal(err)
	}

	ctx := context.Background()

	// OCR: POST /v1/files, then POST /v1/ocr
	pdf, _ := os.ReadFile("document.pdf")
	ocr, err := cl.OCR(ctx, mistralai.OCRRequest{
		Filename:    "document.pdf",
		Content:     bytes.NewReader(pdf),
		ContentType: "application/pdf",
	})
	if err != nil {
		log.Fatal(err)
	}
	log.Println(ocr.Pages[0].Markdown)

	// Chat — one system + one user message; optional markdown/json formatting
	chat, err := cl.Chat(ctx, mistralai.ChatRequest{
		Input:  "Summarize the document in one sentence.",
		Format: mistralai.OutputText,
	})
	if err != nil {
		log.Fatal(err)
	}
	log.Println(chat.Content)

	// ChatCompletion — multi-turn or custom parameters
	resp, err := cl.ChatCompletion(ctx, mistralai.ChatCompletionRequest{
		Model: "mistral-small-latest",
		Messages: []mistralai.ChatMessage{
			{Role: "system", Content: "You are concise."},
			{Role: "user", Content: "Hello"},
		},
		Temperature: new(0.7), // pointer so temperature 0 is distinguishable from unset
	})
	if err != nil {
		log.Fatal(err)
	}
	log.Println(resp.FirstChoiceContent())

	// ListModels
	models, err := cl.ListModels(ctx)
	if err != nil {
		log.Fatal(err)
	}
	for _, m := range models.Data {
		log.Println(m.ID)
	}
}
High-level Chat vs ChatCompletion
  • Chat builds a short message list from Input and optional System, and can request text, markdown, or JSON output via Format / ResponseFormat.
  • ChatCompletion maps directly to the REST request body: any number of messages, sampling controls (temperature, top_p, max_tokens, stop, random_seed, presence_penalty, frequency_penalty, n), response_format, tool calling (tools, tool_choice, parallel_tool_calls), predicted outputs (prediction, see PredictionContent), prompt caching (prompt_cache_key), reasoning (reasoning_effort), and safe_prompt. Use this for conversation history or app-specific control. The stream field is reserved; setting it returns an error until SSE streaming is implemented.

Chat is implemented on top of ChatCompletion internally.

Tool calling

Expose functions to the model via tools on ChatCompletionRequest. When the model needs data, it returns tool_calls on the assistant message; run your handlers and send role: "tool" messages back, then call ChatCompletion again (or use ChatCompletionWithTools to run that loop).

parallel_tool_calls defaults to true on the Mistral API when omitted, so the model may request multiple functions in one assistant turn.

Do not combine response_format: json_schema with tools on the same request.

paramsSchema := map[string]any{
	"type": "object",
	"properties": map[string]any{
		"building_id": map[string]any{"type": "integer"},
	},
}
tools := []mistralai.Tool{
	mistralai.FunctionTool("count_apartments", "Count apartments in confirmed project data", paramsSchema),
}

handler := func(ctx context.Context, call mistralai.ToolCall) (string, error) {
	// Parse call.Function.Arguments (JSON string), run your Go logic, return JSON text.
	return `{"count":8}`, nil
}

resp, err := mistralai.ChatCompletionWithTools(ctx, cl, mistralai.ChatCompletionRequest{
	Model: mistralai.DefaultChatModel,
	Messages: []mistralai.ChatMessage{
		mistralai.TextMessage(mistralai.RoleUser, "How many apartments?"),
	},
	Tools:      tools,
	ToolChoice: mistralai.ToolChoiceMode(mistralai.ToolChoiceAuto),
}, handler, 3)
if err != nil {
	log.Fatal(err)
}
answer, err := resp.FirstChoiceContent()

Manual loop: check choice, _ := resp.FirstChoice() and choice.HasToolCalls(), append choice.Message plus mistralai.ToolMessage(call.ID, call.Function.Name, result) for each call, then call ChatCompletion again with the extended Messages slice.

Embeddings
resp, err := cl.Embeddings(ctx, mistralai.EmbeddingRequest{
	Model: mistralai.EmbeddingModelMistralEmbed,
	Input: mistralai.EmbeddingInputStrings(
		"Embed this sentence.",
		"As well as this one.",
	),
})
if err != nil {
	log.Fatal(err)
}
vecs, err := resp.Float64Vectors()
if err != nil {
	log.Fatal(err)
}
log.Println(len(vecs), len(vecs[0]))

Optional request fields: encoding_format (float or base64), output_dimension, output_dtype (float, int8, uint8, binary, ubinary), and metadata. Decode each vector with EmbeddingData.Float64s() or Float32s() (handles JSON float arrays and base64-encoded float32 payloads).

For batch jobs on /v1/embeddings, use EmbeddingEntry and ParseBatchResults[mistralai.EmbeddingResponse].

Client options
  • WithHTTPClient — custom http.Client (default timeout 10 minutes, suitable for OCR).
  • WithMaxRetries — retries after the initial attempt for retryable status codes (default 4, i.e. 5 attempts total; 0 disables retries).
  • WithBaseURL — override API origin (tests or proxies).
Mocking and dependency inversion

NewClient returns a concrete *Client (not an interface) so new endpoints can be added without breaking your code. For testing or dependency inversion, define a narrow interface in your own package with just the methods you use — *Client satisfies it implicitly:

type ocrClient interface {
	OCR(ctx context.Context, req mistralai.OCRRequest) (mistralai.OCRResponse, error)
}

Package helpers accept small role interfaces, all satisfied by *Client: ChatCompletionWithTools and ChatStructured[T] take a ChatCompleter, WaitForBatchJob takes a BatchJobGetter, and OCRStructured[T] takes an OCRRunner — so you can drive them with a fake in tests.

JSON output with Chat
resp, err := cl.Chat(ctx, mistralai.ChatRequest{
	Input:  `{"task":"translate","text":"hello"}`,
	Format: mistralai.OutputJSON,
})
var out map[string]string
if err = resp.JSON(&out); err != nil {
	log.Fatal(err)
}

For json_schema, set ResponseFormat on ChatRequest, ChatCompletionRequest, or OCRRequest.DocumentAnnotationFormat. Unmarshal OCR output with OCRStructured[T] or DocumentAnnotationInto[T](resp).

Ergonomic helpers
  • new(v) (Go 1.26 built-in) — set optional pointer fields (Temperature, TopP, ExtractHeader, IncludeImageBase64, …) inline; new(0.0) is an explicit zero, a nil pointer is "unset".
  • JSONSchemaFormat(name, schema) — build a strict json_schema *ResponseFormat without hand-writing the ResponseFormat/JSONSchema nesting.
  • TextMessage(role, text) / MultipartMessage(role, parts...) and TextPart, FilePart, ImageURLPart, DocumentURLPart — build messages and multimodal content without magic strings.
  • FunctionTool(name, description, parameters) / ToolMessage(toolCallID, name, content) / ChatCompletionWithTools — function calling on chat completions.
  • RoleSystem, RoleUser, RoleAssistant, RoleTool and ResponseFormatText, ResponseFormatJSONObject, ResponseFormatJSONSchema constants for the role and response_format type fields.
req := mistralai.ChatCompletionRequest{
	Model: mistralai.ChatModelPixtralLargeLatest,
	Messages: []mistralai.ChatMessage{
		mistralai.TextMessage(mistralai.RoleSystem, "Classify the document."),
		mistralai.MultipartMessage(mistralai.RoleUser,
			mistralai.TextPart("What kind of document is this?"),
			mistralai.FilePart(fileID), // from cl.UploadFile
		),
	},
	Temperature:    new(0.0),
	ResponseFormat: mistralai.JSONSchemaFormat("doc_type", schema),
}
Batch API

The Batch API runs one endpoint over many requests asynchronously (roughly half the per-token cost, no per-request rate limits) and returns results as a JSONL file. It is not for latency-sensitive calls — a job completes within its timeout_hours (default 24), not immediately.

Build the input from the same typed request values you already use: ChatCompletionEntry for /v1/chat/completions, EmbeddingEntry for /v1/embeddings, OCREntry for /v1/ocr (referencing an already-uploaded file_id), OCRURLEntry for /v1/ocr over a document URL, or Entry(customID, body) for any other endpoint. Parse results back into the matching typed response with ParseBatchResults[T].

entries := []mistralai.BatchEntry{
	mistralai.ChatCompletionEntry("0", mistralai.ChatCompletionRequest{
		Model:    mistralai.ChatModelMistralSmallLatest,
		Messages: []mistralai.ChatMessage{mistralai.TextMessage(mistralai.RoleUser, "Hello")},
	}),
	mistralai.ChatCompletionEntry("1", mistralai.ChatCompletionRequest{
		Model:    mistralai.ChatModelMistralSmallLatest,
		Messages: []mistralai.ChatMessage{mistralai.TextMessage(mistralai.RoleUser, "Bonjour")},
	}),
}

inputFileID, err := cl.UploadBatchInput(ctx, "batch.jsonl", entries)
if err != nil {
	log.Fatal(err)
}

job, err := cl.CreateBatchJob(ctx, mistralai.CreateBatchJobRequest{
	Endpoint:   mistralai.BatchEndpointChatCompletions,
	Model:      mistralai.ChatModelMistralSmallLatest, // required at job level; defaults per endpoint if omitted
	InputFiles: []string{inputFileID},
})
if err != nil {
	log.Fatal(err)
}

// Poll until terminal (SUCCESS / FAILED / TIMEOUT_EXCEEDED / CANCELLED).
waitCtx, cancel := context.WithTimeout(ctx, time.Hour)
defer cancel()
job, err = mistralai.WaitForBatchJob(waitCtx, cl, job.ID, 10*time.Second)
if err != nil {
	log.Fatal(err)
}

if job.Status == mistralai.BatchStatusSuccess && job.OutputFile != nil {
	raw, err := cl.DownloadFile(ctx, *job.OutputFile)
	if err != nil {
		log.Fatal(err)
	}
	results, err := mistralai.ParseBatchResults[mistralai.ChatCompletionResponse](raw)
	if err != nil {
		log.Fatal(err)
	}
	for _, r := range results {
		if r.StatusCode == 200 {
			content, _ := r.Body.FirstChoiceContent()
			log.Println(r.CustomID, content)
		}
	}
}

WaitForBatchJob returns terminal-but-failed jobs without a Go error — inspect job.Errors and download job.ErrorFile (also JSONL, parse with ParseBatchResults[T]) to see per-request failures. The input file is not deleted automatically; use DeleteFile when you no longer need it.

Error handling

Non-200 responses return a typed *APIError. Inspect it with errors.As to branch on the HTTP status, error type, or whether the client already retried it:

resp, err := cl.Chat(ctx, req)
var apiErr *mistralai.APIError
if errors.As(err, &apiErr) {
	switch apiErr.StatusCode {
	case http.StatusUnauthorized:
		log.Fatal("bad API key")
	case http.StatusTooManyRequests:
		// apiErr.Retryable() == true; the client already exhausted WithMaxRetries
	}
}

Comparison with other Go Mistral clients

There is no official Go SDK for Mistral. The table below compares mistralai-go with the three most widely used community clients (state as of May 2026):

Capability mistralai-go gage-technologies robertjkeck2 onkyou/go-mistral
Chat completions ✅ ✅ ✅ ✅
Streaming chat ❌ ✅ ✅ ✅
Embeddings ✅ ✅ ✅ ✅
FIM / code completion ❌ ✅ ❌ ❌
Function / tool calling ✅ ✅ ❌ ✅
Moderation / classification ❌ ❌ ❌ ✅
OCR + document annotation ✅ ❌ ❌ ❌
File API (upload / list / delete / download) ✅ ❌ ❌ ❌
Batch API (typed entries + typed results) ✅ ❌ ❌ ❌
List models ✅ ✅ ✅ ❌
response_format: json_object ✅ ✅ ❌ ✅
response_format: json_schema (strict) ✅ ❌ ❌ ✅
Typed structured-output helpers (generics) ✅ ❌ ❌ partial
Multimodal content parts (file / image / document URL) ✅ ❌ ❌ ❌
Built-in retries (429 / 5xx, backoff) ✅ ✅ ❌ ❌
Typed API error (errors.As) ✅ partial partial ✅
What mistralai-go does that the others do not
  • OCR (mistral-ocr-latest) with the upload→OCR→cleanup flow handled for you, plus document annotation (json_schema-driven structured extraction) — no other client implements the OCR endpoint.
  • A first-class Files API (UploadFile, ListFiles with pagination/filters, DeleteFile, DownloadFile).
  • The Batch API with an ergonomic typed contract: build input from ChatCompletionRequest/OCR/arbitrary bodies (UploadBatchInput), create/poll/cancel jobs (WaitForBatchJob), and parse results straight into ChatCompletionResponse/OCRResponse (ParseBatchResults[T]) — no hand-rolled JSONL.
  • Strict json_schema structured output with generic helpers (OCRStructured[T], ChatStructured[T], DocumentAnnotationInto[T]).
  • Multimodal message parts (FilePart, ImageURLPart, DocumentURLPart) for vision/document chat.
What mistralai-go does NOT do (yet)

If you need any of the following, one of the clients above will serve you better today:

  • Streaming responses — mistralai-go is fully synchronous (blocks until the complete JSON body returns). All three other clients support streamed chat. The OCR-first design assumes a single blocking call.
  • FIM / code completion (Codestral) — available in gage-technologies.
  • Moderation and classification — available only in onkyou/go-mistral.
  • Agents and fine-tuning — not implemented by any of these clients, including this one.

In short: choose mistralai-go for OCR, document/file workflows, tool calling, and strict structured output; reach for gage-technologies/mistral-go for streaming and FIM, and onkyou/go-mistral if you specifically need moderation/classification.

Testing

go test ./...
Live OCR test
MISTRAL_API_KEY=... go test -tags=mistral_test ./...

License

MIT

Documentation

Overview

Package mistralai is a client for the Mistral AI platform API: chat completions, embeddings, OCR, files, and the batch API.

Field conventions

Request fields are pointers if and only if an explicit zero value differs from leaving the field unset (e.g. *bool toggles, *int page numbers). Everything else is a plain value, so requests can be built with flat composite literals.

Validation policy

Client-side validation covers only structurally required fields and mutual exclusivity — never enum membership, so new server-side values (models, formats, dtypes) work without an SDK release. Validation failures wrap ErrInvalidRequest; API-side rejections surface as *APIError.

Index

Constants

View Source 
const (
	BatchEndpointChatCompletions     = "/v1/chat/completions"
	BatchEndpointEmbeddings          = "/v1/embeddings"
	BatchEndpointFIMCompletions      = "/v1/fim/completions"
	BatchEndpointModerations         = "/v1/moderations"
	BatchEndpointChatModerations     = "/v1/chat/moderations"
	BatchEndpointOCR                 = "/v1/ocr"
	BatchEndpointClassifications     = "/v1/classifications"
	BatchEndpointChatClassifications = "/v1/chat/classifications"
	BatchEndpointConversations       = "/v1/conversations"
	BatchEndpointAudioTranscriptions = "/v1/audio/transcriptions"
)

Batch endpoints accepted by CreateBatchJobRequest.Endpoint. Any string is allowed (forward compatibility); these constants document the set supported by the Mistral Batch API.

View Source 
const (
	ChatModelMistralSmallLatest  = "mistral-small-latest"
	ChatModelMistralMediumLatest = "mistral-medium-latest"
	ChatModelPixtral12BLatest    = "pixtral-12b-latest"
	ChatModelPixtralLargeLatest  = "pixtral-large-latest"

	// DefaultChatModel is used when ChatRequest.Model is empty. It is also the
	// job-level model CreateBatchJob defaults to for the chat batch endpoint.
	DefaultChatModel = ChatModelMistralSmallLatest
)
View Source 
const (
	RoleSystem    = "system"
	RoleUser      = "user"
	RoleAssistant = "assistant"
)

Chat message role values for ChatMessage.Role.

View Source 
const (
	ContentPartText        = "text"
	ContentPartFile        = "file"
	ContentPartImageURL    = "image_url"
	ContentPartDocumentURL = "document_url"
)

Content part type values for ChatMessageContentPart.Type.

View Source 
const (
	ReasoningEffortHigh = "high"
	ReasoningEffortNone = "none"
)

ReasoningEffort values for ChatCompletionRequest.ReasoningEffort.

View Source 
const (
	// DefaultBaseURL is the Mistral cloud API origin.
	DefaultBaseURL = "https://api.mistral.ai"
	// DefaultOCRModel is used when OCRRequest.Model is empty. It is also the
	// job-level model CreateBatchJob defaults to for the OCR batch endpoint.
	DefaultOCRModel = "mistral-ocr-latest"

	// FilePurposeOCR and FilePurposeBatch are the purposes accepted by
	// UploadFile (UploadFileRequest.Purpose).
	FilePurposeOCR   = "ocr"
	FilePurposeBatch = "batch"
)
View Source 
const (
	EmbeddingModelMistralEmbed = "mistral-embed"

	EncodingFormatFloat  = "float"
	EncodingFormatBase64 = "base64"
	OutputDTypeFloat     = "float"
	OutputDTypeInt8      = "int8"
	OutputDTypeUint8     = "uint8"
	OutputDTypeBinary    = "binary"
	OutputDTypeUBinary   = "ubinary"
)
View Source 
const (
	ResponseFormatText       = "text"
	ResponseFormatJSONObject = "json_object"
	ResponseFormatJSONSchema = "json_schema"
)

Response format type values for ResponseFormat.Type.

View Source 
const (
	RoleTool = "tool"

	ToolTypeFunction = "function"

	FinishReasonStop      = "stop"
	FinishReasonToolCalls = "tool_calls"

	ToolChoiceAuto     = "auto"
	ToolChoiceNone     = "none"
	ToolChoiceAny      = "any"
	ToolChoiceRequired = "required"
)

Tool and finish-reason constants aligned with Mistral Chat Completions API.

View Source 
const PredictionTypeContent = "content"

PredictionTypeContent is the only prediction type the API accepts.

View Source 
const (
	// PromptModeReasoning enables the reasoning system prompt on reasoning models.
	// Deprecated by the API in favor of ReasoningEffort.
	PromptModeReasoning = "reasoning"
)

PromptMode values for ChatCompletionRequest.PromptMode.

Variables

View Source 
var ErrInvalidRequest = errors.New("mistral: invalid request")

ErrInvalidRequest wraps every client-side (pre-flight) validation error, so callers can detect them with errors.Is(err, ErrInvalidRequest) instead of matching message text. It is never returned for API-side rejections; those surface as *APIError.

View Source 
var Version = moduleVersion()

Version is the module version sent in the User-Agent header of every request. It is resolved best-effort from Go build info at init: importers of the module see the tagged version; builds from inside the repo (and tests) see "(devel)".

Functions

func BuildBatchInputJSONL 

func BuildBatchInputJSONL(entries []BatchEntry) ([]byte, error)

BuildBatchInputJSONL serializes entries into newline-delimited JSON (one {"custom_id":...,"body":...} object per line). It validates that there is at least one entry, that every custom id is non-empty and unique, and that no body is nil.

func DocumentAnnotationInto 

func DocumentAnnotationInto[T any](r OCRResponse) (T, error)

DocumentAnnotationInto unmarshals document_annotation from an OCR response into T.

func ParseJSON 

func ParseJSON[T any](raw string) (T, error)

ParseJSON unmarshals raw JSON into T.

func ResultsByCustomID 

func ResultsByCustomID[T any](results []BatchResult[T]) map[string]BatchResult[T]

ResultsByCustomID indexes parsed batch results by their custom id. When custom ids repeat, the last occurrence wins.

Types

type APIError 

type APIError struct {
	// StatusCode is the HTTP status code of the response.
	StatusCode int
	// Message is the human-readable message from the API, when present.
	Message string
	// Type is the Mistral error type (e.g. "invalid_request_error"), when present.
	Type string
	// Code is the Mistral error code, when present.
	Code string
	// Body is the raw response body.
	Body []byte
}

APIError is returned when the Mistral API responds with a non-200 status. Inspect it with errors.As: 

var apiErr *mistralai.APIError
if errors.As(err, &apiErr) && apiErr.StatusCode == http.StatusUnauthorized {
	// handle bad API key
}

func (*APIError) Error 

func (e *APIError) Error() string

func (*APIError) Retryable 

func (e *APIError) Retryable() bool

Retryable reports whether the client retries this status (429 and 5xx).

type BatchEntry 

type BatchEntry struct {
	// CustomID uniquely identifies the entry within the file and is echoed back
	// on the matching result line (see ParseBatchResults).
	CustomID string
	// Body is the endpoint request payload (e.g. ChatCompletionRequest).
	Body any
}

BatchEntry is one line of a batch input JSONL file: a unique custom id and the request body for the job's endpoint. Build entries with ChatCompletionEntry, OCREntry, or the generic Entry, then pass them to UploadBatchInput.

func ChatCompletionEntry 

func ChatCompletionEntry(customID string, req ChatCompletionRequest) BatchEntry

ChatCompletionEntry builds a batch entry for the /v1/chat/completions endpoint from a typed ChatCompletionRequest.

func EmbeddingEntry 

func EmbeddingEntry(customID string, req EmbeddingRequest) BatchEntry

EmbeddingEntry builds a batch entry for the /v1/embeddings endpoint from a typed EmbeddingRequest.

func Entry 

func Entry(customID string, body any) BatchEntry

Entry builds a batch entry from an arbitrary request body. Use it for endpoints this package does not type yet; the body is JSON-encoded as-is.

func OCREntry 

func OCREntry(customID, model, fileID string, opts ...OCREntryOption) BatchEntry

OCREntry builds a batch entry for the /v1/ocr endpoint. Unlike the synchronous OCR call, a batch OCR body references a file that has already been uploaded (see UploadFile), so pass its file id rather than raw content. model defaults to DefaultOCRModel when empty.

func OCRURLEntry 

func OCRURLEntry(customID, model, documentURL string, opts ...OCREntryOption) BatchEntry

OCRURLEntry builds a batch entry for the /v1/ocr endpoint that references a document by URL instead of an uploaded file id. model defaults to DefaultOCRModel when empty.

type BatchJob 

type BatchJob struct {
	ID                string            `json:"id"`
	Object            string            `json:"object"` // "batch"
	Status            BatchStatus       `json:"status"`
	Endpoint          string            `json:"endpoint"`
	Model             *string           `json:"model"`
	InputFiles        []string          `json:"input_files"`
	Metadata          map[string]string `json:"metadata,omitempty"`
	CreatedAt         int64             `json:"created_at"`
	StartedAt         *int64            `json:"started_at"`
	CompletedAt       *int64            `json:"completed_at"`
	TotalRequests     int               `json:"total_requests"`
	SucceededRequests int               `json:"succeeded_requests"`
	FailedRequests    int               `json:"failed_requests"`
	CompletedRequests int               `json:"completed_requests"`
	Errors            []BatchJobError   `json:"errors,omitempty"`
	OutputFile        *string           `json:"output_file"`
	ErrorFile         *string           `json:"error_file"`
	Outputs           json.RawMessage   `json:"outputs,omitempty"`
	AgentID           *string           `json:"agent_id,omitempty"`
}

BatchJob is a batch job record (Mistral BatchJobOut).

func WaitForBatchJob 

func WaitForBatchJob(ctx context.Context, c BatchJobGetter, jobID string, pollInterval time.Duration) (BatchJob, error)

WaitForBatchJob polls GetBatchJob every pollInterval (default 5s) until the job reaches a terminal status (SUCCESS, FAILED, TIMEOUT_EXCEEDED, CANCELLED) or ctx is done. It polls once immediately, then on each tick. Wrap ctx with context.WithTimeout to bound the total wait.

A terminal-but-failed job (FAILED, TIMEOUT_EXCEEDED) is returned without a Go error; inspect BatchJob.Errors and download BatchJob.ErrorFile to handle it.

type BatchJobError 

type BatchJobError struct {
	Message string `json:"message"`
}

BatchJobError is one job-level error reported on a batch job.

type BatchJobGetter 

type BatchJobGetter interface {
	GetBatchJob(ctx context.Context, jobID string) (BatchJob, error)
}

BatchJobGetter fetches batch jobs; satisfied by *Client. It is the dependency of WaitForBatchJob.

type BatchJobList 

type BatchJobList struct {
	Object string     `json:"object"` // "list"
	Data   []BatchJob `json:"data"`
	Total  int        `json:"total"`
}

BatchJobList is the list batch jobs API response.

type BatchResult 

type BatchResult[T any] struct {
	ID         string
	CustomID   string
	StatusCode int
	Body       T
	// Error is the raw error payload of a failed entry (nil on success);
	// unmarshal it into your own type as needed.
	Error json.RawMessage
}

BatchResult is one parsed line of a batch output (or error) file, keyed by the entry's custom id. Body is populated only when StatusCode is 200; otherwise it is the zero value of T and Error/StatusCode describe the failure.

func ParseBatchResults 

func ParseBatchResults[T any](jsonl []byte) ([]BatchResult[T], error)

ParseBatchResults parses batch output JSONL (from DownloadFile) into typed results, preserving file order. T is the endpoint's response type (e.g. ChatCompletionResponse, OCRResponse). For each line with status_code 200 and no error, response.body is unmarshaled into T; other lines keep their StatusCode and Error with a zero Body. Blank lines are skipped.

type BatchStatus 

type BatchStatus string

BatchStatus is a batch job lifecycle state. 

const (
	BatchStatusQueued                BatchStatus = "QUEUED"
	BatchStatusRunning               BatchStatus = "RUNNING"
	BatchStatusSuccess               BatchStatus = "SUCCESS"
	BatchStatusFailed                BatchStatus = "FAILED"
	BatchStatusTimeoutExceeded       BatchStatus = "TIMEOUT_EXCEEDED"
	BatchStatusCancellationRequested BatchStatus = "CANCELLATION_REQUESTED"
	BatchStatusCancelled             BatchStatus = "CANCELLED"
)

func (BatchStatus) IsTerminal 

func (s BatchStatus) IsTerminal() bool

IsTerminal reports whether no further status transitions are expected. CANCELLATION_REQUESTED is non-terminal: it transitions to CANCELLED.

type ChatCompleter 

type ChatCompleter interface {
	ChatCompletion(ctx context.Context, req ChatCompletionRequest) (ChatCompletionResponse, error)
}

ChatCompleter runs chat completions; satisfied by *Client. It is the dependency of ChatCompletionWithTools and ChatStructured.

type ChatCompletionRequest 

type ChatCompletionRequest struct {
	Model       string        `json:"model"`
	Messages    []ChatMessage `json:"messages"`
	Temperature *float64      `json:"temperature,omitempty"`
	MaxTokens   int           `json:"max_tokens,omitempty"`
	TopP        *float64      `json:"top_p,omitempty"`
	// Stream is reserved for SSE streaming, which this client does not support
	// yet; ChatCompletion returns an error when it is set.
	Stream bool `json:"stream,omitempty"`
	// Stop lists tokens that end generation when detected.
	Stop []string `json:"stop,omitempty"`
	// RandomSeed makes sampling deterministic across calls when set.
	RandomSeed *int `json:"random_seed,omitempty"`
	// Metadata is arbitrary metadata stored with the request.
	Metadata       map[string]any  `json:"metadata,omitempty"`
	ResponseFormat *ResponseFormat `json:"response_format,omitempty"`
	Tools          []Tool          `json:"tools,omitempty"`
	// ToolChoice selects the tool-calling mode or forces one function; build it
	// with ToolChoiceMode or ToolChoiceFunction.
	ToolChoice ToolChoice `json:"tool_choice,omitzero"`
	// PresencePenalty (-2..2) penalizes words that already appeared at all;
	// pointer so an explicit 0 differs from unset.
	PresencePenalty *float64 `json:"presence_penalty,omitempty"`
	// FrequencyPenalty (-2..2) penalizes words by how often they already appeared.
	FrequencyPenalty *float64 `json:"frequency_penalty,omitempty"`
	// N is the number of completions to return; input tokens are billed once.
	N *int `json:"n,omitempty"`
	// Prediction supplies expected output content to reduce latency (see PredictionContent).
	Prediction        *Prediction `json:"prediction,omitempty"`
	ParallelToolCalls *bool       `json:"parallel_tool_calls,omitempty"`
	// PromptMode toggles the reasoning system prompt (PromptModeReasoning).
	PromptMode string `json:"prompt_mode,omitempty"`
	// ReasoningEffort controls reasoning traces on reasoning models
	// (ReasoningEffortHigh or ReasoningEffortNone).
	ReasoningEffort string `json:"reasoning_effort,omitempty"`
	// PromptCacheKey enables prompt caching: requests sharing the same key and
	// prompt prefix reuse computed tokens at reduced input cost.
	PromptCacheKey string `json:"prompt_cache_key,omitempty"`
	// SafePrompt injects a safety prompt before the conversation.
	SafePrompt bool `json:"safe_prompt,omitempty"`
}

ChatCompletionRequest is the body for POST /v1/chat/completions.

type ChatCompletionResponse 

type ChatCompletionResponse struct {
	ID      string                         `json:"id"`
	Model   string                         `json:"model"`
	Choices []ChatCompletionResponseChoice `json:"choices"`
	Object  string                         `json:"object"`
	Usage   UsageInfo                      `json:"usage"`
}

ChatCompletionResponse is the successful chat completions API payload.

func ChatCompletionWithTools 

func ChatCompletionWithTools(
	ctx context.Context,
	c ChatCompleter,
	req ChatCompletionRequest,
	handler ToolHandler,
	maxRounds int,
) (ChatCompletionResponse, error)

ChatCompletionWithTools runs chat completion in a tool-calling loop until the model returns a final text response or maxRounds is exceeded.

Each round where the model returns tool_calls: the assistant message and one tool message per call are appended to req.Messages, then ChatCompletion runs again with the same tools configuration. Parallel tool calls in one assistant turn are all executed before the next completion.

Do not set ResponseFormat on req when using tools; structured output and tool calling should not be combined in the same request. A maxRounds of 3 is usually sufficient for chained tool use.

func ChatStructured 

func ChatStructured[T any](ctx context.Context, c ChatCompleter, req ChatCompletionRequest) (T, ChatCompletionResponse, error)

ChatStructured runs ChatCompletion and unmarshals the first choice content into T.

func (ChatCompletionResponse) AllChoicesContent 

func (r ChatCompletionResponse) AllChoicesContent() string

AllChoicesContent concatenates assistant content from every choice.

func (ChatCompletionResponse) FirstChoice 

func (r ChatCompletionResponse) FirstChoice() (ChatCompletionResponseChoice, error)

FirstChoice returns the first completion choice or an error if missing.

func (ChatCompletionResponse) FirstChoiceContent 

func (r ChatCompletionResponse) FirstChoiceContent() (string, error)

FirstChoiceContent returns trimmed content from the first choice, or an error if missing/empty.

type ChatCompletionResponseChoice 

type ChatCompletionResponseChoice struct {
	Index        int         `json:"index"`
	Message      ChatMessage `json:"message"`
	FinishReason string      `json:"finish_reason"`
}

ChatCompletionResponseChoice is one completion choice.

func (ChatCompletionResponseChoice) HasToolCalls 

func (c ChatCompletionResponseChoice) HasToolCalls() bool

HasToolCalls reports whether the choice message contains tool calls.

type ChatMessage 

type ChatMessage struct {
	Role       string     `json:"role"`
	Content    any        `json:"content"`
	ToolCalls  []ToolCall `json:"tool_calls,omitempty"`
	ToolCallID string     `json:"tool_call_id,omitempty"`
	Name       string     `json:"name,omitempty"`
}

ChatMessage is one message in a chat completion request or response.

func AssistantToolCallsMessage 

func AssistantToolCallsMessage(calls []ToolCall) ChatMessage

AssistantToolCallsMessage builds an assistant message that requests tool calls.

func MultipartMessage 

func MultipartMessage(role string, parts ...ChatMessageContentPart) ChatMessage

MultipartMessage builds a ChatMessage whose content is a list of multimodal parts (see TextPart, FilePart, ImageURLPart, DocumentURLPart).

func TextMessage 

func TextMessage(role, text string) ChatMessage

TextMessage builds a plain-text ChatMessage for the given role (RoleSystem, RoleUser, or RoleAssistant).

func ToolMessage 

func ToolMessage(toolCallID, name, content string) ChatMessage

ToolMessage builds a tool result message for a prior tool_call.

type ChatMessageContentPart 

type ChatMessageContentPart struct {
	Type        string `json:"type"`
	Text        string `json:"text,omitempty"`
	FileID      string `json:"file_id,omitempty"`
	DocumentURL string `json:"document_url,omitempty"`
	ImageURL    string `json:"image_url,omitempty"`
}

ChatMessageContentPart is one multimodal content item for Chat Completions.

func DocumentURLPart 

func DocumentURLPart(url string) ChatMessageContentPart

DocumentURLPart references a document by URL.

func FilePart 

func FilePart(fileID string) ChatMessageContentPart

FilePart references a previously uploaded file by its API file id (see Client.UploadFile).

func ImageURLPart 

func ImageURLPart(url string) ChatMessageContentPart

ImageURLPart references an image by URL.

func TextPart 

func TextPart(text string) ChatMessageContentPart

TextPart is a text content part.

type ChatRequest 

type ChatRequest struct {
	// Input is the user message (required).
	Input string
	// System is an optional system instruction prepended before Input.
	System string
	// Model overrides DefaultChatModel when non-empty.
	Model string
	// Format requests text, markdown, or json output. Defaults to OutputText.
	Format OutputFormat
	// ResponseFormat optionally refines JSON output (e.g. json_schema). When Format is
	// OutputJSON and this is nil, json_object mode is used.
	ResponseFormat *ResponseFormat
}

ChatRequest is a chat completion with arbitrary user text.

type ChatResponse 

type ChatResponse struct {
	Content string
	Format  OutputFormat
	Model   string
}

ChatResponse is the assistant message from a chat completion.

func (ChatResponse) JSON 

func (r ChatResponse) JSON(dest any) error

JSON unmarshals Content into dest when Format is OutputJSON.

type Client 

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

Client is a synchronous HTTP client for the Mistral API. Construct it with NewClient. Methods are safe for concurrent use.

Client is intentionally a concrete struct, not an interface, so new API endpoints can be added without breaking consumers. For dependency inversion or mocking, define a narrow interface with just the methods you use: 

type ocrClient interface {
	OCR(ctx context.Context, req mistralai.OCRRequest) (mistralai.OCRResponse, error)
}

Helpers in this package that take a client accept such role interfaces (ChatCompleter, BatchJobGetter, OCRRunner), all satisfied by *Client.

func NewClient 

func NewClient(apiKey string, opts ...ClientOption) (*Client, error)

NewClient returns a synchronous HTTP client for the Mistral API. apiKey is required; an empty key returns an error.

func (*Client) CancelBatchJob 

func (c *Client) CancelBatchJob(ctx context.Context, jobID string) (BatchJob, error)

CancelBatchJob requests cancellation (POST /v1/batch/jobs/{job_id}/cancel).

func (*Client) Chat 

func (c *Client) Chat(ctx context.Context, req ChatRequest) (ChatResponse, error)

Chat runs POST /v1/chat/completions with a single user turn and optional system prompt and output format helpers (see ChatRequest).

func (*Client) ChatCompletion 

func (c *Client) ChatCompletion(ctx context.Context, req ChatCompletionRequest) (ChatCompletionResponse, error)

ChatCompletion runs POST /v1/chat/completions with full message control.

func (*Client) CreateBatchJob 

func (c *Client) CreateBatchJob(ctx context.Context, req CreateBatchJobRequest) (BatchJob, error)

CreateBatchJob creates an async batch job (POST /v1/batch/jobs).

func (*Client) DeleteFile 

func (c *Client) DeleteFile(ctx context.Context, fileID string) error

DeleteFile removes an uploaded file (DELETE /v1/files/{file_id}).

func (*Client) DownloadFile 

func (c *Client) DownloadFile(ctx context.Context, fileID string) ([]byte, error)

DownloadFile downloads raw file content (GET /v1/files/{file_id}/content). Use it to fetch a batch job's OutputFile or ErrorFile, then parse the bytes with ParseBatchResults.

func (*Client) Embeddings 

func (c *Client) Embeddings(ctx context.Context, req EmbeddingRequest) (EmbeddingResponse, error)

Embeddings runs POST /v1/embeddings. Model is required (e.g. EmbeddingModelMistralEmbed); like the other raw-request methods, this one never defaults it.

func (*Client) GetBatchJob 

func (c *Client) GetBatchJob(ctx context.Context, jobID string) (BatchJob, error)

GetBatchJob fetches one batch job (GET /v1/batch/jobs/{job_id}).

func (*Client) ListBatchJobs 

func (c *Client) ListBatchJobs(ctx context.Context, req ListBatchJobsRequest) (BatchJobList, error)

ListBatchJobs lists batch jobs for the API key (GET /v1/batch/jobs).

func (*Client) ListFiles 

func (c *Client) ListFiles(ctx context.Context, req ListFilesRequest) (FileList, error)

ListFiles returns files for the API key (GET /v1/files).

func (*Client) ListModels 

func (c *Client) ListModels(ctx context.Context) (ModelList, error)

ListModels returns models available to the API key (GET /v1/models).

func (*Client) OCR 

func (c *Client) OCR(ctx context.Context, req OCRRequest) (OCRResponse, error)

OCR uploads the document via POST /v1/files, then runs POST /v1/ocr on the uploaded file id; the file is deleted afterwards (best effort).

func (*Client) OCRByFileID 

func (c *Client) OCRByFileID(ctx context.Context, req OCRFileRequest) (OCRResponse, error)

OCRByFileID runs POST /v1/ocr for a file already uploaded via UploadFile. The caller is responsible for deleting the file when finished.

func (*Client) OCRByURL 

func (c *Client) OCRByURL(ctx context.Context, req OCRURLRequest) (OCRResponse, error)

OCRByURL runs POST /v1/ocr on a document or image referenced by URL, skipping the file upload round-trip.

func (*Client) UploadBatchInput 

func (c *Client) UploadBatchInput(ctx context.Context, filename string, entries []BatchEntry) (string, error)

UploadBatchInput builds a JSONL input file from entries and uploads it with purpose "batch", returning the file id for CreateBatchJobRequest.InputFiles.

func (*Client) UploadFile 

func (c *Client) UploadFile(ctx context.Context, req UploadFileRequest) (string, error)

UploadFile uploads file bytes (POST /v1/files) and returns the API file id. Purpose defaults to FilePurposeOCR; use FilePurposeBatch for batch inputs.

type ClientOption 

type ClientOption func(*clientOptions)

ClientOption configures optional NewClient settings. API key is always required separately.

func WithBaseURL 

func WithBaseURL(baseURL string) ClientOption

WithBaseURL overrides DefaultBaseURL, e.g. to route requests through a proxy or API gateway, or to point tests at a local server.

func WithHTTPClient 

func WithHTTPClient(httpClient *http.Client) ClientOption

WithHTTPClient sets the HTTP client used for Mistral API calls.

func WithMaxRetries 

func WithMaxRetries(n int) ClientOption

WithMaxRetries sets how many times a failed request is retried after the initial attempt, for retryable failures (429/5xx and transport errors). 0 disables retries; negative values are treated as 0. Default is 4 retries (5 attempts in total).

type CreateBatchJobRequest 

type CreateBatchJobRequest struct {
	// Endpoint is the target API endpoint (required). Use a BatchEndpoint* constant.
	Endpoint string
	// InputFiles are JSONL file ids (see UploadBatchInput). At least one is required.
	InputFiles []string
	// Model is required by the Batch API at job level (per-entry body model is optional then).
	// When empty, CreateBatchJob defaults by endpoint (OCR → DefaultOCRModel, chat → DefaultChatModel).
	Model string
	// Metadata is arbitrary metadata stored on the job. The Batch API constrains
	// values to strings (unlike chat/embeddings metadata, which allows any JSON).
	Metadata map[string]string
	// TimeoutHours bounds job runtime; 0 omits the field (API default is 24).
	TimeoutHours int
}

CreateBatchJobRequest is the body for POST /v1/batch/jobs.

type EmbeddingData 

type EmbeddingData struct {
	Index     int             `json:"index"`
	Object    string          `json:"object"`
	Embedding json.RawMessage `json:"embedding"`
}

EmbeddingData is one vector in an embeddings response.

func (EmbeddingData) Float32s 

func (d EmbeddingData) Float32s() ([]float32, error)

Float32s decodes the embedding as float32 values (base64 payloads are decoded as float32; JSON float arrays are narrowed).

func (EmbeddingData) Float64s 

func (d EmbeddingData) Float64s() ([]float64, error)

Float64s decodes the embedding as a float slice. For encoding_format "float" this is a direct JSON array; for "base64" it decodes little-endian float32 bytes.

type EmbeddingInput 

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

EmbeddingInput is the request "input" field: one string or a batch of strings.

func EmbeddingInputString 

func EmbeddingInputString(s string) EmbeddingInput

EmbeddingInputString embeds a single string.

func EmbeddingInputStrings 

func EmbeddingInputStrings(ss ...string) EmbeddingInput

EmbeddingInputStrings embeds multiple strings in one request.

func (EmbeddingInput) MarshalJSON 

func (in EmbeddingInput) MarshalJSON() ([]byte, error)

MarshalJSON encodes a string or []string per the Mistral embeddings API.

type EmbeddingRequest 

type EmbeddingRequest struct {
	Model           string         `json:"model"`
	Input           EmbeddingInput `json:"input"`
	EncodingFormat  string         `json:"encoding_format,omitempty"`
	OutputDimension *int           `json:"output_dimension,omitempty"`
	OutputDType     string         `json:"output_dtype,omitempty"`
	Metadata        map[string]any `json:"metadata,omitempty"`
}

EmbeddingRequest is the body for POST /v1/embeddings.

type EmbeddingResponse 

type EmbeddingResponse struct {
	ID     string          `json:"id"`
	Object string          `json:"object"`
	Model  string          `json:"model"`
	Data   []EmbeddingData `json:"data"`
	Usage  UsageInfo       `json:"usage"`
}

EmbeddingResponse is the successful embeddings API payload.

func (EmbeddingResponse) Float64Vectors 

func (r EmbeddingResponse) Float64Vectors() ([][]float64, error)

Float64Vectors returns decoded vectors for every data item, in index order.

type File 

type File struct {
	ID         string  `json:"id"`
	Object     string  `json:"object"`
	Bytes      *int64  `json:"bytes"`
	CreatedAt  int64   `json:"created_at"`
	Filename   string  `json:"filename"`
	Purpose    string  `json:"purpose"`
	SampleType string  `json:"sample_type"`
	NumLines   *int    `json:"num_lines,omitempty"`
	Mimetype   *string `json:"mimetype,omitempty"`
	Source     string  `json:"source"`
	Signature  *string `json:"signature,omitempty"`
	ExpiresAt  *int64  `json:"expires_at,omitempty"`
	Visibility *string `json:"visibility,omitempty"`
}

File is an uploaded file metadata record (Mistral FileSchema).

type FileList 

type FileList struct {
	Object string `json:"object"`
	Data   []File `json:"data"`
	Total  *int   `json:"total,omitempty"`
}

FileList is the list files API response (Mistral ListFilesOut).

type FunctionCall 

type FunctionCall struct {
	Name      string `json:"name"`
	Arguments string `json:"arguments"`
}

FunctionCall holds the function name and JSON-encoded arguments string.

type FunctionDef 

type FunctionDef struct {
	Name        string         `json:"name"`
	Description string         `json:"description,omitempty"`
	Parameters  map[string]any `json:"parameters"`
	Strict      bool           `json:"strict,omitempty"`
}

FunctionDef describes a function the model may invoke.

type JSONSchema 

type JSONSchema struct {
	Name        string         `json:"name"`
	Description string         `json:"description,omitempty"`
	Schema      map[string]any `json:"schema"`
	Strict      bool           `json:"strict,omitempty"`
}

JSONSchema is the schema wrapper for document_annotation_format.

type ListBatchJobsRequest 

type ListBatchJobsRequest struct {
	Page        *int
	PageSize    *int
	CreatedByMe *bool
}

ListBatchJobsRequest filters and paginates GET /v1/batch/jobs.

type ListFilesRequest 

type ListFilesRequest struct {
	Page         *int
	PageSize     *int
	IncludeTotal *bool
	SampleType   []string
	Source       []string
	Search       string
	Purpose      string
	Mimetypes    []string
}

ListFilesRequest filters and pagination for GET /v1/files. Zero value lists files with API defaults (page=0, page_size=100, include_total=true).

type ModelCard 

type ModelCard struct {
	ID      string `json:"id"`
	Object  string `json:"object"`
	Created int64  `json:"created"`
	OwnedBy string `json:"owned_by"`
}

ModelCard describes a Mistral model from GET /v1/models.

type ModelList 

type ModelList struct {
	Object string      `json:"object"`
	Data   []ModelCard `json:"data"`
}

ModelList is the list models API response.

type NamedToolChoice 

type NamedToolChoice struct {
	Type     string              `json:"type"`
	Function NamedToolChoiceFunc `json:"function"`
}

NamedToolChoice forces the model to call one function by name.

type NamedToolChoiceFunc 

type NamedToolChoiceFunc struct {
	Name string `json:"name"`
}

NamedToolChoiceFunc is the function name inside a named tool_choice.

type OCREntryOption 

type OCREntryOption func(*OCROptions)

OCREntryOption configures the optional fields of an OCR batch entry body. The With* helpers below cover the common fields; custom options can set any OCROptions field directly.

func WithOCRDocumentAnnotation 

func WithOCRDocumentAnnotation(prompt string, format *ResponseFormat) OCREntryOption

WithOCRDocumentAnnotation sets a structured-extraction prompt and its required response format (see JSONSchemaFormat).

func WithOCRExtractFooter 

func WithOCRExtractFooter(extract bool) OCREntryOption

WithOCRExtractFooter toggles document footer extraction.

func WithOCRExtractHeader 

func WithOCRExtractHeader(extract bool) OCREntryOption

WithOCRExtractHeader toggles document header extraction.

func WithOCRImageBase64 

func WithOCRImageBase64(include bool) OCREntryOption

WithOCRImageBase64 requests base64 image payloads in the response.

func WithOCRPages 

func WithOCRPages(pages ...int) OCREntryOption

WithOCRPages limits OCR to the given zero-based page indices.

func WithOCRTableFormat 

func WithOCRTableFormat(format string) OCREntryOption

WithOCRTableFormat sets the table output format ("markdown" or "html").

type OCRFileRequest added in v0.17.0 

type OCRFileRequest struct {
	// FileID is the uploaded file's id (required).
	FileID string
	// Model overrides DefaultOCRModel when non-empty.
	Model string
	// Pages limits processing to zero-based page indices.
	Pages []int
	// TableFormat is "markdown" or "html" when set.
	TableFormat string
	// IncludeImageBase64 requests base64 image payloads in the response when true.
	IncludeImageBase64 *bool
	ExtractHeader      *bool
	ExtractFooter      *bool
	// ID is an optional client-side correlation id forwarded to the API.
	ID string
	// DocumentAnnotationPrompt guides structured extraction for the whole document.
	// DocumentAnnotationFormat must be set when using a prompt.
	DocumentAnnotationPrompt string
	DocumentAnnotationFormat *ResponseFormat
}

OCRFileRequest describes OCR of a file already uploaded via UploadFile.

type OCRImage 

type OCRImage struct {
	ID           string `json:"id"`
	TopLeftX     int    `json:"top_left_x"`
	TopLeftY     int    `json:"top_left_y"`
	BottomRightX int    `json:"bottom_right_x"`
	BottomRightY int    `json:"bottom_right_y"`
	ImageBase64  string `json:"image_base64,omitempty"`
}

OCRImage is an extracted image on an OCR page.

type OCROptions added in v0.17.0 

type OCROptions struct {
	// Pages limits processing to zero-based page indices.
	Pages []int
	// TableFormat is "markdown" or "html" when set.
	TableFormat string
	// IncludeImageBase64 requests base64 image payloads in the response when true.
	IncludeImageBase64 *bool
	ExtractHeader      *bool
	ExtractFooter      *bool
	// ID is an optional client-side correlation id forwarded to the API.
	ID string
	// DocumentAnnotationPrompt guides structured extraction for the whole document.
	// DocumentAnnotationFormat must be set when using a prompt.
	DocumentAnnotationPrompt string
	DocumentAnnotationFormat *ResponseFormat
}

OCROptions holds the optional processing fields shared by every OCR entry point. The synchronous requests (OCRRequest, OCRURLRequest, OCRFileRequest) expose the same fields flat; batch entries set them via OCREntryOption.

type OCRPage 

type OCRPage struct {
	Index      int                `json:"index"`
	Markdown   string             `json:"markdown"`
	Images     []OCRImage         `json:"images,omitempty"`
	Tables     []OCRTable         `json:"tables,omitempty"`
	Hyperlinks []string           `json:"hyperlinks,omitempty"`
	Header     *string            `json:"header,omitempty"`
	Footer     *string            `json:"footer,omitempty"`
	Dimensions *OCRPageDimensions `json:"dimensions,omitempty"`
}

OCRPage is one page from a Mistral OCR response.

type OCRPageDimensions 

type OCRPageDimensions struct {
	DPI    int `json:"dpi"`
	Height int `json:"height"`
	Width  int `json:"width"`
}

OCRPageDimensions holds page size metadata from OCR.

type OCRRequest 

type OCRRequest struct {
	// Filename is sent in multipart upload (e.g. "invoice.pdf").
	Filename string
	// Content is the raw file bytes.
	Content io.Reader
	// ContentType is optional; when empty, application/octet-stream is used.
	ContentType string
	// Model overrides DefaultOCRModel when non-empty.
	Model string
	// Pages limits processing to zero-based page indices.
	Pages []int
	// TableFormat is "markdown" or "html" when set.
	TableFormat string
	// IncludeImageBase64 requests base64 image payloads in the response when true.
	IncludeImageBase64 *bool
	ExtractHeader      *bool
	ExtractFooter      *bool
	// ID is an optional client-side correlation id forwarded to the API.
	ID string
	// DocumentAnnotationPrompt guides structured extraction for the whole document.
	// DocumentAnnotationFormat must be set when using a prompt.
	DocumentAnnotationPrompt string
	DocumentAnnotationFormat *ResponseFormat
}

OCRRequest describes a document to OCR via file upload (not a URL). The client performs POST /v1/files (multipart, purpose=ocr), then POST /v1/ocr with the returned file id.

type OCRResponse 

type OCRResponse struct {
	Pages              []OCRPage    `json:"pages"`
	Model              string       `json:"model"`
	DocumentAnnotation *string      `json:"document_annotation,omitempty"`
	UsageInfo          OCRUsageInfo `json:"usage_info"`
}

OCRResponse is the successful OCR API payload.

func OCRStructured 

func OCRStructured[T any](ctx context.Context, c OCRRunner, req OCRRequest) (T, OCRResponse, error)

OCRStructured runs OCR and unmarshals document_annotation into T.

type OCRRunner 

type OCRRunner interface {
	OCR(ctx context.Context, req OCRRequest) (OCRResponse, error)
}

OCRRunner runs upload-based OCR; satisfied by *Client. It is the dependency of OCRStructured.

type OCRTable 

type OCRTable struct {
	ID      string `json:"id"`
	Content string `json:"content"`
	Format  string `json:"format"`
}

OCRTable is an extracted table on an OCR page.

type OCRURLRequest 

type OCRURLRequest struct {
	// DocumentURL references a document (e.g. a PDF) by URL.
	DocumentURL string
	// DocumentName optionally names the document; only valid with DocumentURL.
	DocumentName string
	// ImageURL references an image by https URL or data: URI.
	ImageURL string
	// Model overrides DefaultOCRModel when non-empty.
	Model string
	// Pages limits processing to zero-based page indices.
	Pages []int
	// TableFormat is "markdown" or "html" when set.
	TableFormat string
	// IncludeImageBase64 requests base64 image payloads in the response when true.
	IncludeImageBase64 *bool
	ExtractHeader      *bool
	ExtractFooter      *bool
	// ID is an optional client-side correlation id forwarded to the API.
	ID string
	// DocumentAnnotationPrompt guides structured extraction for the whole document.
	// DocumentAnnotationFormat must be set when using a prompt.
	DocumentAnnotationPrompt string
	DocumentAnnotationFormat *ResponseFormat
}

OCRURLRequest describes a document to OCR by URL instead of file upload. Exactly one of DocumentURL or ImageURL is required.

type OCRUsageInfo 

type OCRUsageInfo struct {
	PagesProcessed int    `json:"pages_processed"`
	DocSizeBytes   *int64 `json:"doc_size_bytes"`
}

OCRUsageInfo reports billing-related OCR usage.

type OutputFormat 

type OutputFormat string

OutputFormat selects how the model should structure its reply. 

const (
	OutputText     OutputFormat = "text"
	OutputMarkdown OutputFormat = "markdown"
	OutputJSON     OutputFormat = "json"
)

type Prediction 

type Prediction struct {
	Type    string `json:"type"`
	Content string `json:"content"`
}

Prediction supplies expected completion content so the API can skip generating tokens that match it, reducing latency for edit-style tasks (see PredictionContent).

func PredictionContent 

func PredictionContent(content string) *Prediction

PredictionContent builds a content prediction for ChatCompletionRequest.Prediction.

type ResponseFormat 

type ResponseFormat struct {
	Type       string      `json:"type"`
	JSONSchema *JSONSchema `json:"json_schema,omitempty"`
}

ResponseFormat selects structured output for chat completions (ChatCompletionRequest.ResponseFormat) and OCR document annotations.

func JSONSchemaFormat 

func JSONSchemaFormat(name string, schema map[string]any) *ResponseFormat

JSONSchemaFormat builds a strict json_schema response_format from a schema name and a JSON Schema document. Use it for ChatCompletionRequest.ResponseFormat, ChatRequest.ResponseFormat, and OCRRequest.DocumentAnnotationFormat.

type Tool 

type Tool struct {
	Type     string      `json:"type"`
	Function FunctionDef `json:"function"`
}

Tool is one callable function exposed to the model.

func FunctionTool 

func FunctionTool(name, description string, parameters map[string]any) Tool

FunctionTool builds a function tool definition. A nil parameters map defaults to an empty object schema so the request never sends "parameters": null.

type ToolCall 

type ToolCall struct {
	ID       string       `json:"id"`
	Type     string       `json:"type"`
	Index    *int         `json:"index,omitempty"`
	Function FunctionCall `json:"function"`
}

ToolCall is one function invocation requested by the model.

type ToolChoice added in v0.17.0 

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

ToolChoice is the chat tool_choice union: a mode string or a forced named function. Build it with ToolChoiceMode or ToolChoiceFunction; the zero value omits the field from the request.

func ToolChoiceFunction added in v0.17.0 

func ToolChoiceFunction(name string) ToolChoice

ToolChoiceFunction forces the model to call the named function.

func ToolChoiceMode added in v0.17.0 

func ToolChoiceMode(mode string) ToolChoice

ToolChoiceMode selects a tool-choice mode: ToolChoiceAuto, ToolChoiceNone, ToolChoiceAny, or ToolChoiceRequired.

func (ToolChoice) IsZero added in v0.17.0 

func (t ToolChoice) IsZero() bool

IsZero reports whether the value is unset, so `json:"...,omitzero"` drops it.

func (ToolChoice) MarshalJSON added in v0.17.0 

func (t ToolChoice) MarshalJSON() ([]byte, error)

MarshalJSON encodes a mode string or named-function object per the Mistral chat completions API.

func (*ToolChoice) UnmarshalJSON added in v0.17.0 

func (t *ToolChoice) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes either union shape, so request bodies round-trip (e.g. through batch JSONL).

type ToolHandler 

type ToolHandler func(ctx context.Context, call ToolCall) (content string, err error)

ToolHandler executes one tool call and returns the result content string (typically JSON) sent back to the model in a tool message.

type UploadFileRequest 

type UploadFileRequest struct {
	Filename    string
	Content     io.Reader
	ContentType string
	Purpose     string
}

UploadFileRequest uploads a file to Mistral files API.

type UsageInfo 

type UsageInfo struct {
	PromptTokens     int `json:"prompt_tokens"`
	CompletionTokens int `json:"completion_tokens"`
	TotalTokens      int `json:"total_tokens"`
}

UsageInfo reports token usage from a chat completion.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.