ambie

README

ambie-go

Official Go SDK for AMBIE.

Speech-to-text in noisy environments, translation, TTS, embeddings, sentiment, summarization, content moderation, and language detection — over a single typed client.

Install

go get github.com/abundera/ambie-go

Requires Go 1.21+. Zero external dependencies (stdlib only).

Quickstart

package main

import (
	"context"
	"fmt"
	"os"

	ambie "github.com/abundera/ambie-go"
)

func main() {
	c, err := ambie.New(os.Getenv("AMBIE_API_KEY"))
	if err != nil {
		panic(err)
	}

	ctx := context.Background()

	// Transcribe a file
	audio, _ := os.ReadFile("meeting.mp3")
	r, err := c.Transcribe(ctx, ambie.TranscribeOptions{
		Audio:     audio,
		AudioName: "meeting.mp3",
		Engine:    "deepgram",
		Diarize:   true,
		Summarize: true,
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(r.Text)
	fmt.Println(r.Summary)

	// Translate text
	t, _ := c.Translate(ctx, ambie.TranslateOptions{
		Text:       "Hello, world!",
		TargetLang: "es",
	})
	fmt.Println(t.TranslatedText)
}

Async mode

accepted, err := c.TranscribeAsync(ctx, ambie.TranscribeOptions{
	URL:         "https://cdn.example.com/long-recording.mp3",
	CallbackURL: "https://yourserver.com/webhooks/ambie",
})
fmt.Println(accepted.RequestID, accepted.PollURL)

// Or poll status manually:
status, _ := c.GetTranscribeJob(ctx, accepted.RequestID)

Webhook verification

import (
	ambie "github.com/abundera/ambie-go"
)

func handle(w http.ResponseWriter, r *http.Request) {
	body, _ := io.ReadAll(r.Body)
	err := ambie.VerifyWebhookSignature(ambie.VerifyWebhookOptions{
		Signature: r.Header.Get("X-Ambie-Signature"),
		Body:      body,
		Secret:    os.Getenv("AMBIE_WEBHOOK_SECRET"),
	})
	if err != nil {
		http.Error(w, "invalid signature", http.StatusUnauthorized)
		return
	}
	// safe to parse and act on body
}

Configuration

c, err := ambie.New(apiKey,
	ambie.WithBaseURL("https://staging.ambie.ai"),
	ambie.WithMaxRetries(5),
	ambie.WithUserAgent("my-app/1.0"),
	ambie.WithHTTPClient(&http.Client{Timeout: 90 * time.Second}),
)

Error handling

r, err := c.Transcribe(ctx, opts)
if err != nil {
	var apiErr *ambie.Error
	if errors.As(err, &apiErr) {
		fmt.Println(apiErr.Status, apiErr.Code, apiErr.Message, apiErr.RequestID)
	}
}

Coverage

Supported endpoints: Transcribe, Translate, TTS, Sentiment, Summarize, Embeddings, Rerank, Moderate, DetectLanguage. Each has a sync method and async polling via Get<Endpoint>Job(ctx, requestID).

See the full OpenAPI 3.1 spec.

License

MIT © AMBIE

Documentation

Overview

Package ambie is the official Go SDK for AMBIE.

See https://ambie.ai/sdk for the full API reference.

Index

• Constants
• func VerifyWebhookSignature(opts VerifyWebhookOptions) error
• type ActionItem
• type AsyncAccepted
• type Chapter
• type Client
  • func New(apiKey string, opts ...Option) (*Client, error)
  • func (c *Client) DetectLanguage(ctx context.Context, opts DetectLangOptions) (*DetectLangResult, error)
  • func (c *Client) Embeddings(ctx context.Context, opts EmbeddingsOptions) (*EmbeddingsResult, error)
  • func (c *Client) GetTranscribeJob(ctx context.Context, requestID string) (*JobStatus, error)
  • func (c *Client) GetTranslateJob(ctx context.Context, requestID string) (*JobStatus, error)
  • func (c *Client) GetTtsJob(ctx context.Context, requestID string) (*JobStatus, error)
  • func (c *Client) Moderate(ctx context.Context, opts ModerateOptions) (*ModerateResult, error)
  • func (c *Client) Rerank(ctx context.Context, opts RerankOptions) (*RerankResult, error)
  • func (c *Client) Sentiment(ctx context.Context, opts SentimentOptions) (*SentimentResult, error)
  • func (c *Client) Summarize(ctx context.Context, opts SummarizeOptions) (*SummarizeResult, error)
  • func (c *Client) TTS(ctx context.Context, opts TtsOptions) (*TtsResult, error)
  • func (c *Client) Transcribe(ctx context.Context, opts TranscribeOptions) (*TranscriptionResult, error)
  • func (c *Client) TranscribeAsync(ctx context.Context, opts TranscribeOptions) (*AsyncAccepted, error)
  • func (c *Client) Translate(ctx context.Context, opts TranslateOptions) (*TranslationResult, error)
• type DetectLangAlternative
• type DetectLangOptions
• type DetectLangResult
• type EmbeddingsOptions
• type EmbeddingsResult
• type Error
  • func (e *Error) Error() string
• type JobStatus
• type ModerateOptions
• type ModerateResult
• type Option
  • func WithBaseURL(u string) Option
  • func WithHTTPClient(h *http.Client) Option
  • func WithMaxRetries(n int) Option
  • func WithUserAgent(ua string) Option
• type RerankItem
• type RerankOptions
• type RerankResult
• type SentimentItem
• type SentimentOptions
• type SentimentResult
• type SummarizeOptions
• type SummarizeResult
• type TranscribeOptions
• type TranscriptionResult
• type TranslateOptions
• type TranslationResult
• type TtsOptions
• type TtsResult
• type Utterance
• type VerifyWebhookOptions
• type Word

Constants

const DefaultToleranceSeconds = 300

DefaultToleranceSeconds is the default maximum age for a webhook signature.

Functions

func VerifyWebhookSignature

func VerifyWebhookSignature(opts VerifyWebhookOptions) error

VerifyWebhookSignature verifies a Stripe-compatible webhook signature of the form "t=<unix_ts>,v1=<hex>". It recomputes HMAC-SHA256 of "{t}.{body}" with the secret and compares in constant time.

Types

type ActionItem

type ActionItem struct {
	Action   string `json:"action"`
	Assignee string `json:"assignee,omitempty"`
	Deadline string `json:"deadline,omitempty"`
}

type AsyncAccepted

type AsyncAccepted struct {
	RequestID string `json:"request_id"`
	PollURL   string `json:"poll_url"`
	Status    string `json:"status"`
	ClientID  string `json:"client_id,omitempty"`
	CreatedAt string `json:"created_at,omitempty"`
}

AsyncAccepted is the response when a callback_url is provided.

type Chapter

type Chapter struct {
	Title   string  `json:"title"`
	Summary string  `json:"summary"`
	Start   float64 `json:"start"`
	End     float64 `json:"end"`
}

type Client

type Client struct {
	APIKey     string
	BaseURL    string
	HTTPClient *http.Client
	MaxRetries int
	UserAgent  string
}

Client is the AMBIE API client.

func New

func New(apiKey string, opts ...Option) (*Client, error)

New returns a Client authenticated with apiKey.

func (*Client) DetectLanguage

func (c *Client) DetectLanguage(ctx context.Context, opts DetectLangOptions) (*DetectLangResult, error)

func (*Client) Embeddings

func (c *Client) Embeddings(ctx context.Context, opts EmbeddingsOptions) (*EmbeddingsResult, error)

func (*Client) GetTranscribeJob

func (c *Client) GetTranscribeJob(ctx context.Context, requestID string) (*JobStatus, error)

GetTranscribeJob polls a transcription job by request_id.

func (*Client) GetTranslateJob

func (c *Client) GetTranslateJob(ctx context.Context, requestID string) (*JobStatus, error)

func (*Client) GetTtsJob

func (c *Client) GetTtsJob(ctx context.Context, requestID string) (*JobStatus, error)

func (*Client) Moderate

func (c *Client) Moderate(ctx context.Context, opts ModerateOptions) (*ModerateResult, error)

func (*Client) Rerank

func (c *Client) Rerank(ctx context.Context, opts RerankOptions) (*RerankResult, error)

func (*Client) Sentiment

func (c *Client) Sentiment(ctx context.Context, opts SentimentOptions) (*SentimentResult, error)

func (*Client) Summarize

func (c *Client) Summarize(ctx context.Context, opts SummarizeOptions) (*SummarizeResult, error)

func (*Client) TTS

func (c *Client) TTS(ctx context.Context, opts TtsOptions) (*TtsResult, error)

func (*Client) Transcribe

func (c *Client) Transcribe(ctx context.Context, opts TranscribeOptions) (*TranscriptionResult, error)

Transcribe uploads an audio file (or fetches a URL) and returns the result. If opts.CallbackURL is set the API returns 202 and you should consume the AsyncAccepted struct (use TranscribeAsync). Use this method only for sync.

func (*Client) TranscribeAsync

func (c *Client) TranscribeAsync(ctx context.Context, opts TranscribeOptions) (*AsyncAccepted, error)

TranscribeAsync submits a transcribe request with a callback URL and returns the AsyncAccepted handle. opts.CallbackURL must be set.

func (*Client) Translate

func (c *Client) Translate(ctx context.Context, opts TranslateOptions) (*TranslationResult, error)

type DetectLangAlternative

type DetectLangAlternative struct {
	Language   string  `json:"language"`
	Confidence float64 `json:"confidence"`
}

type DetectLangOptions

type DetectLangOptions struct {
	Text        string `json:"text"`
	CallbackURL string `json:"callback_url,omitempty"`
	ClientID    string `json:"client_id,omitempty"`
}

type DetectLangResult

type DetectLangResult struct {
	RequestID    string                  `json:"request_id"`
	ClientID     string                  `json:"client_id,omitempty"`
	Language     string                  `json:"language"`
	Confidence   float64                 `json:"confidence"`
	Alternatives []DetectLangAlternative `json:"alternatives,omitempty"`
}

type EmbeddingsOptions

type EmbeddingsOptions struct {
	Text        any    `json:"text"` // string or []string
	Model       string `json:"model,omitempty"`
	CallbackURL string `json:"callback_url,omitempty"`
	ClientID    string `json:"client_id,omitempty"`
}

type EmbeddingsResult

type EmbeddingsResult struct {
	RequestID  string      `json:"request_id"`
	ClientID   string      `json:"client_id,omitempty"`
	Model      string      `json:"model"`
	Dimensions int         `json:"dimensions"`
	Embeddings [][]float64 `json:"embeddings"`
}

type Error

type Error struct {
	Status    int    `json:"status"`
	Code      string `json:"code"`
	Message   string `json:"message"`
	RequestID string `json:"request_id,omitempty"`
}

Error is returned for any non-2xx API response after retries.

func (*Error) Error

func (e *Error) Error() string

type JobStatus

type JobStatus struct {
	RequestID   string         `json:"request_id"`
	Status      string         `json:"status"`
	ClientID    string         `json:"client_id,omitempty"`
	Result      map[string]any `json:"result,omitempty"`
	Error       string         `json:"error,omitempty"`
	CreatedAt   string         `json:"created_at,omitempty"`
	CompletedAt string         `json:"completed_at,omitempty"`
}

JobStatus is the response from a status polling endpoint.

type ModerateOptions

type ModerateOptions struct {
	Text        string `json:"text"`
	CallbackURL string `json:"callback_url,omitempty"`
	ClientID    string `json:"client_id,omitempty"`
}

type ModerateResult

type ModerateResult struct {
	RequestID  string             `json:"request_id"`
	ClientID   string             `json:"client_id,omitempty"`
	Flagged    bool               `json:"flagged"`
	Categories map[string]bool    `json:"categories"`
	Scores     map[string]float64 `json:"scores,omitempty"`
}

type Option

type Option func(*Client)

Option configures a Client.

func WithBaseURL

func WithBaseURL(u string) Option

WithBaseURL overrides the default base URL.

func WithHTTPClient

func WithHTTPClient(h *http.Client) Option

WithHTTPClient injects a custom HTTP client.

func WithMaxRetries

func WithMaxRetries(n int) Option

WithMaxRetries sets retry attempts on 429/5xx (default 3).

func WithUserAgent

func WithUserAgent(ua string) Option

WithUserAgent overrides the User-Agent header.

type RerankItem

type RerankItem struct {
	Index    int     `json:"index"`
	Score    float64 `json:"score"`
	Document string  `json:"document"`
}

type RerankOptions

type RerankOptions struct {
	Query       string   `json:"query"`
	Documents   []string `json:"documents"`
	TopK        int      `json:"top_k,omitempty"`
	CallbackURL string   `json:"callback_url,omitempty"`
	ClientID    string   `json:"client_id,omitempty"`
}

type RerankResult

type RerankResult struct {
	RequestID string       `json:"request_id"`
	ClientID  string       `json:"client_id,omitempty"`
	Results   []RerankItem `json:"results"`
}

type SentimentItem

type SentimentItem struct {
	Text  string  `json:"text"`
	Label string  `json:"label"`
	Score float64 `json:"score"`
}

type SentimentOptions

type SentimentOptions struct {
	Text        any    `json:"text"` // string or []string
	CallbackURL string `json:"callback_url,omitempty"`
	ClientID    string `json:"client_id,omitempty"`
}

type SentimentResult

type SentimentResult struct {
	RequestID string          `json:"request_id"`
	ClientID  string          `json:"client_id,omitempty"`
	Results   []SentimentItem `json:"results"`
}

type SummarizeOptions

type SummarizeOptions struct {
	Text        string `json:"text,omitempty"`
	URL         string `json:"url,omitempty"`
	MaxLength   int    `json:"max_length,omitempty"`
	CallbackURL string `json:"callback_url,omitempty"`
	ClientID    string `json:"client_id,omitempty"`
}

type SummarizeResult

type SummarizeResult struct {
	RequestID     string `json:"request_id"`
	ClientID      string `json:"client_id,omitempty"`
	Summary       string `json:"summary"`
	SourceLength  int    `json:"source_length,omitempty"`
	SummaryLength int    `json:"summary_length,omitempty"`
}

type TranscribeOptions

type TranscribeOptions struct {
	Audio       []byte
	AudioName   string // optional; defaults to "audio.bin"
	URL         string
	Engine      string // "deepgram" (default) or "whisper"
	Language    string
	Format      string // "json" (default), "text", "srt", "vtt"
	Translate   bool
	CallbackURL string
	ClientID    string
	Diarize     bool
	Summarize   bool
	KeyPhrases  bool
	ActionItems bool
	Chapters    bool
	// Extra holds any other fields documented in openapi.yaml
	// (punctuate, smart_format, multichannel, vocabulary, etc.).
	Extra map[string]string
}

TranscribeOptions configures a transcription request. Either Audio or URL is required. Audio takes a filename and the raw bytes.

type TranscriptionResult

type TranscriptionResult struct {
	RequestID    string       `json:"request_id"`
	ClientID     string       `json:"client_id,omitempty"`
	Engine       string       `json:"engine"`
	Language     string       `json:"language,omitempty"`
	Duration     float64      `json:"duration"`
	Text         string       `json:"text"`
	Confidence   float64      `json:"confidence,omitempty"`
	Words        []Word       `json:"words,omitempty"`
	Utterances   []Utterance  `json:"utterances,omitempty"`
	DiarizedText string       `json:"diarized_text,omitempty"`
	SpeakerCount int          `json:"speaker_count,omitempty"`
	Paragraphs   []string     `json:"paragraphs,omitempty"`
	Summary      string       `json:"summary,omitempty"`
	KeyPhrases   []string     `json:"key_phrases,omitempty"`
	ActionItems  []ActionItem `json:"action_items,omitempty"`
	Chapters     []Chapter    `json:"chapters,omitempty"`
}

type TranslateOptions

type TranslateOptions struct {
	Text        string `json:"text"`
	TargetLang  string `json:"target_lang"`
	SourceLang  string `json:"source_lang,omitempty"`
	Formality   string `json:"formality,omitempty"`
	Context     string `json:"context,omitempty"`
	CallbackURL string `json:"callback_url,omitempty"`
	ClientID    string `json:"client_id,omitempty"`
}

type TranslationResult

type TranslationResult struct {
	RequestID      string  `json:"request_id"`
	ClientID       string  `json:"client_id,omitempty"`
	SourceLang     string  `json:"source_lang"`
	TargetLang     string  `json:"target_lang"`
	SourceText     string  `json:"source_text"`
	TranslatedText string  `json:"translated_text"`
	Confidence     float64 `json:"confidence,omitempty"`
}

type TtsOptions

type TtsOptions struct {
	Text        string  `json:"text"`
	Voice       string  `json:"voice,omitempty"`
	Engine      string  `json:"engine,omitempty"`
	Language    string  `json:"language,omitempty"`
	Encoding    string  `json:"encoding,omitempty"`
	Container   string  `json:"container,omitempty"`
	Speed       float64 `json:"speed,omitempty"`
	CallbackURL string  `json:"callback_url,omitempty"`
	ClientID    string  `json:"client_id,omitempty"`
}

type TtsResult

type TtsResult struct {
	RequestID string  `json:"request_id"`
	ClientID  string  `json:"client_id,omitempty"`
	AudioURL  string  `json:"audio_url"`
	Duration  float64 `json:"duration,omitempty"`
	Voice     string  `json:"voice"`
	Encoding  string  `json:"encoding"`
}

type Utterance

type Utterance struct {
	Text       string  `json:"text"`
	Start      float64 `json:"start"`
	End        float64 `json:"end"`
	Confidence float64 `json:"confidence,omitempty"`
	Speaker    int     `json:"speaker,omitempty"`
}

type VerifyWebhookOptions

type VerifyWebhookOptions struct {
	Signature        string // X-Ambie-Signature header value
	Body             []byte // raw request body bytes (NOT parsed JSON)
	Secret           string // webhook secret from /signup
	ToleranceSeconds int    // 0 = use default (300)
	NowFunc          func() int64
}

VerifyWebhookOptions configures VerifyWebhookSignature.

type Word

type Word struct {
	Word       string  `json:"word"`
	Start      float64 `json:"start"`
	End        float64 `json:"end"`
	Confidence float64 `json:"confidence,omitempty"`
	Speaker    int     `json:"speaker,omitempty"`
	Channel    int     `json:"channel,omitempty"`
}