minimax

README

minimax-go

Go SDK and examples for MiniMax APIs.

What is included

• Speech APIs
  • synchronous HTTP TTS
  • streaming TTS
  • async TTS task submit/query
• File upload API
• Voice APIs
  • list voices
  • voice design
  • voice clone

Requirements

• Go 1.26+
• MiniMax API key

Quick start

Set your API key:

export MINIMAX_API_KEY="your_api_key"

Check runnable examples:

go run ./examples/speech -h
go run ./examples/speech async -h
go run ./examples/speech stream -h
go run ./examples/speech http -h
go run ./examples/voice/list -h
go run ./examples/file -h

Development checks

go fmt ./...
go build ./...
go vet ./...
go test ./...

Repository layout

• client.go: SDK client and service wiring
• speech*.go: speech sync/stream/async APIs
• voice.go: voice-related APIs
• file.go: file upload API
• internal/: transport/protocol/stream/codec internals
• examples/: runnable CLI demos

Documentation

Index

• type Client
  • func NewClient(config Config) (*Client, error)
• type CloneVoiceRequest
• type CloneVoiceResponse
• type Config
• type DesignVoiceRequest
• type DesignVoiceResponse
• type FileMeta
• type FileService
  • func (s *FileService) Upload(ctx context.Context, request FileUploadRequest) (*FileUploadResponse, error)
• type FileUploadRequest
• type FileUploadResponse
• type ListVoicesRequest
• type ListVoicesResponse
• type ResponseMeta
• type SpeechAsyncService
  • func (s *SpeechAsyncService) GetAsyncTask(ctx context.Context, taskID string) (*SpeechTaskStatusResponse, error)
  • func (s *SpeechAsyncService) SubmitAsync(ctx context.Context, request SpeechAsyncSubmitRequest) (*SpeechAsyncSubmitResponse, error)
• type SpeechAsyncSubmitRequest
• type SpeechAsyncSubmitResponse
• type SpeechChunk
• type SpeechRequest
• type SpeechResponse
• type SpeechService
  • func (s *SpeechService) GetAsyncTask(ctx context.Context, taskID string) (*SpeechTaskStatusResponse, error)
  • func (s *SpeechService) OpenStream(ctx context.Context, request SpeechStreamRequest) (*SpeechStream, error)
  • func (s *SpeechService) Stream(ctx context.Context, request SpeechStreamRequest) (*SpeechStream, error)
  • func (s *SpeechService) SubmitAsync(ctx context.Context, request SpeechAsyncSubmitRequest) (*SpeechAsyncSubmitResponse, error)
  • func (s *SpeechService) Synthesize(ctx context.Context, request SpeechRequest) (*SpeechResponse, error)
• type SpeechStream
  • func (s *SpeechStream) Close() error
  • func (s *SpeechStream) Next() (*SpeechChunk, error)
• type SpeechStreamRequest
• type SpeechTaskMeta
• type SpeechTaskResult
• type SpeechTaskState
  • func (s SpeechTaskState) IsTerminal() bool
• type SpeechTaskStatusRequest
• type SpeechTaskStatusResponse
• type Voice
  • func (v *Voice) UnmarshalJSON(data []byte) error
• type VoiceService
  • func (s *VoiceService) CloneVoice(ctx context.Context, request *CloneVoiceRequest) (*CloneVoiceResponse, error)
  • func (s *VoiceService) DesignVoice(ctx context.Context, request *DesignVoiceRequest) (*DesignVoiceResponse, error)
  • func (s *VoiceService) ListVoices(ctx context.Context, request *ListVoicesRequest) (*ListVoicesResponse, error)

Types

type Client

type Client struct {
	Speech      *SpeechService
	SpeechAsync *SpeechAsyncService
	File        *FileService
	Voice       *VoiceService
	// contains filtered or unexported fields
}

func NewClient

func NewClient(config Config) (*Client, error)

type CloneVoiceRequest

type CloneVoiceRequest struct {
	VoiceID  string `json:"voice_id"`
	AudioURL string `json:"audio_url,omitempty"`
	FileID   string `json:"file_id,omitempty"`
}

type CloneVoiceResponse

type CloneVoiceResponse struct {
	ResponseMeta ResponseMeta               `json:"response_meta,omitzero"`
	VoiceID      string                     `json:"voice_id,omitempty"`
	DemoAudio    string                     `json:"demo_audio,omitempty"`
	Raw          map[string]json.RawMessage `json:"-"`
}

type Config

type Config struct {
	BaseURL        string
	APIKey         string
	HTTPClient     *http.Client
	DefaultHeaders http.Header
	Retry          transport.RetryConfig
}

type DesignVoiceRequest

type DesignVoiceRequest struct {
	Prompt      string `json:"prompt"`
	PreviewText string `json:"preview_text"`
	VoiceID     string `json:"voice_id,omitempty"`
}

type DesignVoiceResponse

type DesignVoiceResponse struct {
	ResponseMeta ResponseMeta               `json:"response_meta,omitzero"`
	VoiceID      string                     `json:"voice_id,omitempty"`
	TrialAudio   string                     `json:"trial_audio,omitempty"`
	Raw          map[string]json.RawMessage `json:"-"`
}

type FileMeta

type FileMeta struct {
	FileName    string `json:"file_name,omitempty"`
	ContentType string `json:"content_type,omitempty"`
	Size        int64  `json:"size,omitempty"`
}

type FileService

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

func (*FileService) Upload

func (s *FileService) Upload(ctx context.Context, request FileUploadRequest) (*FileUploadResponse, error)

Upload uploads file bytes through multipart/form-data and returns normalized metadata.

type FileUploadRequest

type FileUploadRequest struct {
	Purpose     string `json:"purpose,omitempty"`
	FileName    string `json:"file_name"`
	ContentType string `json:"content_type,omitempty"`
	Data        []byte `json:"-"`
}

type FileUploadResponse

type FileUploadResponse struct {
	ResponseMeta ResponseMeta `json:"response_meta,omitzero"`
	FileID       string       `json:"file_id,omitempty"`
	FileURL      string       `json:"file_url,omitempty"`
	Uploaded     bool         `json:"uploaded"`
	Meta         FileMeta     `json:"meta,omitempty"`
}

type ListVoicesRequest

type ListVoicesRequest struct {
	VoiceType string `json:"voice_type,omitempty"`
	PageSize  *int   `json:"page_size,omitempty"`
	PageToken string `json:"page_token,omitempty"`
}

type ListVoicesResponse

type ListVoicesResponse struct {
	ResponseMeta  ResponseMeta               `json:"response_meta,omitzero"`
	Voices        []Voice                    `json:"voices"`
	NextPageToken string                     `json:"next_page_token,omitempty"`
	HasMore       bool                       `json:"has_more,omitempty"`
	Raw           map[string]json.RawMessage `json:"-"`
}

type ResponseMeta

type ResponseMeta struct {
	RequestID  string      `json:"request_id,omitempty"`
	TraceID    string      `json:"trace_id,omitempty"`
	HTTPStatus int         `json:"http_status,omitempty"`
	Header     http.Header `json:"-"`
}

ResponseMeta contains transport-level metadata returned by Minimax APIs.

type SpeechAsyncService

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

func (*SpeechAsyncService) GetAsyncTask

func (s *SpeechAsyncService) GetAsyncTask(ctx context.Context, taskID string) (*SpeechTaskStatusResponse, error)

GetAsyncTask queries a speech synthesis async task by task_id.

func (*SpeechAsyncService) SubmitAsync

func (s *SpeechAsyncService) SubmitAsync(ctx context.Context, request SpeechAsyncSubmitRequest) (*SpeechAsyncSubmitResponse, error)

SubmitAsync creates an asynchronous speech synthesis task.

type SpeechAsyncSubmitRequest

type SpeechAsyncSubmitRequest struct {
	Model      string   `json:"model,omitempty"`
	Text       string   `json:"text,omitempty"`
	TextFileID string   `json:"text_file_id,omitempty"`
	VoiceID    string   `json:"voice_id,omitempty"`
	Speed      *float64 `json:"speed,omitempty"`
	Vol        *float64 `json:"vol,omitempty"`
	Pitch      *int     `json:"pitch,omitempty"`
}

type SpeechAsyncSubmitResponse

type SpeechAsyncSubmitResponse struct {
	ResponseMeta    ResponseMeta               `json:"response_meta,omitzero"`
	TaskID          string                     `json:"task_id"`
	Status          SpeechTaskState            `json:"status,omitempty"`
	RawStatus       string                     `json:"raw_status,omitempty"`
	FileID          string                     `json:"file_id,omitempty"`
	TaskToken       string                     `json:"task_token,omitempty"`
	UsageCharacters *int64                     `json:"usage_characters,omitempty"`
	Raw             map[string]json.RawMessage `json:"-"`
}

type SpeechChunk

type SpeechChunk struct {
	Event       string
	Audio       []byte
	RawHexAudio string
	Done        bool
}

type SpeechRequest

type SpeechRequest struct {
	Model   string   `json:"model,omitempty"`
	Text    string   `json:"text"`
	VoiceID string   `json:"voice_id,omitempty"`
	Speed   *float64 `json:"speed,omitempty"`
	Vol     *float64 `json:"vol,omitempty"`
	Pitch   *int     `json:"pitch,omitempty"`
}

type SpeechResponse

type SpeechResponse struct {
	ResponseMeta ResponseMeta
	Audio        []byte
	RawHexAudio  string
}

type SpeechService

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

func (*SpeechService) GetAsyncTask

func (s *SpeechService) GetAsyncTask(ctx context.Context, taskID string) (*SpeechTaskStatusResponse, error)

GetAsyncTask queries an asynchronous speech synthesis task through SpeechService.

func (*SpeechService) OpenStream

func (s *SpeechService) OpenStream(ctx context.Context, request SpeechStreamRequest) (*SpeechStream, error)

OpenStream opens a speech synthesis stream and returns a stream reader.

func (*SpeechService) Stream

func (s *SpeechService) Stream(ctx context.Context, request SpeechStreamRequest) (*SpeechStream, error)

Stream is an alias of OpenStream.

func (*SpeechService) SubmitAsync

func (s *SpeechService) SubmitAsync(ctx context.Context, request SpeechAsyncSubmitRequest) (*SpeechAsyncSubmitResponse, error)

SubmitAsync creates an asynchronous speech synthesis task through SpeechService.

func (*SpeechService) Synthesize

func (s *SpeechService) Synthesize(ctx context.Context, request SpeechRequest) (*SpeechResponse, error)

Synthesize performs sync TTS and returns decoded audio bytes.

type SpeechStream

type SpeechStream struct {
	ResponseMeta ResponseMeta
	// contains filtered or unexported fields
}

SpeechStream reads speech stream events and yields decoded audio chunks.

func (*SpeechStream) Close

func (s *SpeechStream) Close() error

Close closes the underlying stream body.

func (*SpeechStream) Next

func (s *SpeechStream) Next() (*SpeechChunk, error)

Next returns the next speech chunk; returns io.EOF when stream completes.

type SpeechStreamRequest

type SpeechStreamRequest struct {
	Model        string   `json:"model,omitempty"`
	Text         string   `json:"text"`
	VoiceID      string   `json:"voice_id,omitempty"`
	Speed        *float64 `json:"speed,omitempty"`
	Vol          *float64 `json:"vol,omitempty"`
	Pitch        *int     `json:"pitch,omitempty"`
	OutputFormat string   `json:"output_format,omitempty"`
}

type SpeechTaskMeta

type SpeechTaskMeta struct {
	DurationSeconds *float64 `json:"duration_seconds,omitempty"`
	SizeBytes       *int64   `json:"size_bytes,omitempty"`
	Format          string   `json:"format,omitempty"`
	SampleRate      *int     `json:"sample_rate,omitempty"`
	Bitrate         *int     `json:"bitrate,omitempty"`
	Channel         *int     `json:"channel,omitempty"`
}

type SpeechTaskResult

type SpeechTaskResult struct {
	FileID      string         `json:"file_id,omitempty"`
	AudioURL    string         `json:"audio_url,omitempty"`
	RawHexAudio string         `json:"raw_hex_audio,omitempty"`
	Audio       []byte         `json:"audio,omitempty"`
	Meta        SpeechTaskMeta `json:"meta,omitempty"`
}

type SpeechTaskState

type SpeechTaskState string

SpeechTaskState is the normalized async speech task state.

const (
	SpeechTaskStateQueued    SpeechTaskState = "queued"
	SpeechTaskStateRunning   SpeechTaskState = "running"
	SpeechTaskStateSucceeded SpeechTaskState = "succeeded"
	SpeechTaskStateFailed    SpeechTaskState = "failed"
)

func (SpeechTaskState) IsTerminal

func (s SpeechTaskState) IsTerminal() bool

IsTerminal reports whether the task state is terminal.

type SpeechTaskStatusRequest

type SpeechTaskStatusRequest struct {
	TaskID string `json:"task_id"`
}

type SpeechTaskStatusResponse

type SpeechTaskStatusResponse struct {
	ResponseMeta ResponseMeta               `json:"response_meta,omitzero"`
	TaskID       string                     `json:"task_id"`
	Status       SpeechTaskState            `json:"status,omitempty"`
	RawStatus    string                     `json:"raw_status,omitempty"`
	Result       SpeechTaskResult           `json:"result,omitempty"`
	ErrorMessage string                     `json:"error_message,omitempty"`
	Raw          map[string]json.RawMessage `json:"-"`
}

type Voice

type Voice struct {
	VoiceID     string                     `json:"voice_id,omitempty"`
	VoiceName   string                     `json:"voice_name,omitempty"`
	Description []string                   `json:"description,omitempty"`
	CreatedTime string                     `json:"created_time,omitempty"`
	VoiceType   string                     `json:"voice_type,omitempty"`
	Raw         map[string]json.RawMessage `json:"-"`
}

func (*Voice) UnmarshalJSON

func (v *Voice) UnmarshalJSON(data []byte) error

type VoiceService

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

func (*VoiceService) CloneVoice

func (s *VoiceService) CloneVoice(ctx context.Context, request *CloneVoiceRequest) (*CloneVoiceResponse, error)

CloneVoice clones a voice from either an audio URL or a previously uploaded file_id.

func (*VoiceService) DesignVoice

func (s *VoiceService) DesignVoice(ctx context.Context, request *DesignVoiceRequest) (*DesignVoiceResponse, error)

DesignVoice creates a new custom voice based on prompt and preview text.

func (*VoiceService) ListVoices

func (s *VoiceService) ListVoices(ctx context.Context, request *ListVoicesRequest) (*ListVoicesResponse, error)

ListVoices queries available voices with filter and pagination parameters.