api

package
v0.10.13 Latest Latest
Warning

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

 Go to latest Published: Nov 6, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package api wraps the generated Avatar API client with what every command needs: the API key or sign-in, error mapping, X-RateLimit quota, and calls that start GPU work or pay sent without blind resends.

Index

Constants

View Source 
const (
	// MaxCandidatesPerRequest mirrors the API so mistakes fail before a request.
	MaxCandidatesPerRequest = 10
	// MaxPrimeTextChars bounds a v2 preview message (Unicode code points; ~30 s).
	MaxPrimeTextChars = 300
	// JoinWaitTimeout covers a cold v2 pool before the avatar joins a room,
	// and the retries while it warms up.
	JoinWaitTimeout = 10 * time.Minute
)
View Source 
const (
	EngineV1         = "v1"
	EngineV2         = "v2"
	EngineV2Pro      = "v2hd"
	EngineV2ProAlias = "v2pro"
)

The engines: v1, v2 and Atmee V2 HD (v2hd), a larger v2 model that builds, previews and serves like v2. EngineV2ProAlias is V2 HD's first name, which servers before the rename report and every server accepts.

View Source 
const (
	V2AccessGranted        = "granted"
	V2AccessInviteRequired = "invite_required"
	V2AccessUnavailable    = "unavailable"
)

The account's v2 access (v2Access on GET /v1/account and on a redemption).

View Source 
const (
	ResolutionStep           = 32
	MinResolutionSide        = 256
	MaxResolutionSide        = 1024
	MaxResolutionPixels      = 512 * 512
	MaxV2ProResolutionPixels = 864 * 480
)

The renderers' frame rule: each side a multiple of ResolutionStep from MinResolutionSide to MaxResolutionSide, at most MaxResolutionPixels in all for v2 (512x512) and MaxV2ProResolutionPixels for V2 HD (864x480).

View Source 
const (
	ClipRendering = avatarapi.ClipStatusResponseStatusRendering
	ClipReady     = avatarapi.ClipStatusResponseStatusReady
	ClipExpired   = avatarapi.ClipStatusResponseStatusExpired
	ClipStalled   = avatarapi.ClipStatusResponseStatusStalled
)

Clip statuses.

View Source 
const DefaultBaseURL = "https://api.atmanity.us"

DefaultBaseURL is production; ATMEE_BASE_URL points the CLI elsewhere, such as the local mock http://localhost:8091.

View Source 
const MaxConductorBodyBytes = 512 * 1024

MaxConductorBodyBytes is the conductor route's request body cap.

View Source 
const MaxRuntimeSeed = 1<<31 - 1

MaxRuntimeSeed is the largest runtime seed the API takes.

Variables

This section is empty.

Functions

func CanonicalEngine added in v0.10.12 

func CanonicalEngine(e string) string

CanonicalEngine is an engine as given or reported, with V2 HD's first name (v2pro) read as v2hd.

func CheckOffered added in v0.10.11 

func CheckOffered(acct *Account, engine string, r Resolution) error

CheckOffered refuses a frame size the server does not offer the engine, naming the ones it does. Without a list (an older server, or one that offers every size the rule allows) it lets the server decide: the server is the authority either way.

func CheckPrimeText 

func CheckPrimeText(engine, text string) error

CheckPrimeText refuses a v2 preview message the API would refuse.

func CheckResolution 

func CheckResolution(r Resolution) error

CheckResolution refuses a frame size the v2 renderer cannot take.

func CheckResolutionFor added in v0.10.11 

func CheckResolutionFor(engine string, r Resolution) error

CheckResolutionFor refuses a frame size the engine's renderer cannot take.

func CheckRuntimeSeed 

func CheckRuntimeSeed(seed int) error

CheckRuntimeSeed refuses a runtime seed the API would refuse.

func ConductorBody 

func ConductorBody(raw []byte, speakAfterS *float64) ([]byte, error)

ConductorBody builds a PUT /conductor body from a file's JSON: a full request body (an object with a top-level "graph") or a bare graph (any other object). speakAfterS, when set, replaces the body's own. The body's other values are sent as written; the API checks them.

func IsRemote 

func IsRemote(s string) bool

IsRemote says s names a file the API already can reach (an https URL or upload:<uploadId>) rather than a local path.

func IsV2Family added in v0.10.11 

func IsV2Family(engine string) bool

IsV2Family says the engine builds candidates and serves a take: v2 and V2 HD.

func NewIDs 

func NewIDs(before, after *CandidateList) []string

NewIDs are the captures a request just added: the current-version candidates in after (its response) that before (a list read just ahead of it) did not show. The response lists every current candidate, so older captures still queued are in it too; they do not count. When nothing is new, there are no ids, and a wait on them covers every current capture.

func ParseCandidateID 

func ParseCandidateID(s string) (uuid.UUID, error)

ParseCandidateID validates a candidate id before any request. Any UUID spelling (upper case, braces) is accepted; the API sees the canonical one.

func ParseClipRequestID added in v0.10.12 

func ParseClipRequestID(s string) (uuid.UUID, error)

ParseClipRequestID validates a clip's request id (the Idempotency-Key its generate call was sent with) before any request.

func ParseID 

func ParseID(s string) (uuid.UUID, error)

ParseID validates an avatar or session id before any request.

func ParseKeyID 

func ParseKeyID(s string) (uuid.UUID, error)

ParseKeyID validates a key id before any request.

func ParseSpeechSettings 

func ParseSpeechSettings(raw []byte) (map[string]json.RawMessage, error)

ParseSpeechSettings checks a pinned-settings file: a JSON object whose fields are the API's (instructions, persona, facts, ...). The API checks their limits (422 invalid_settings).

func Settled 

func Settled(a *Avatar) bool

Settled reports that nothing more happens without the caller acting: failed, held, a draft waiting for its portrait or voice, or ready / (v2 manual) a candidate waiting to be picked, with no rebuild still capturing new candidates.

func WireEngine added in v0.10.12 

func WireEngine(e string) string

WireEngine is the engine as sent to the API: V2 HD goes as v2pro, the name every server accepts (servers before the rename refuse v2hd).

Types

type APIKey 

type APIKey string

APIKey sends the key as X-Api-Key.

func (APIKey) Authorize 

func (k APIKey) Authorize(_ context.Context, r *http.Request) error

type Account 

type Account struct {
	avatarapi.Account
	// SessionV2Reported is whether pricing carried
	// sessionV2PerMinuteMicrocredits: a server older than the v2 rates leaves
	// it out, and its one conversation rate covers both engines. It tells
	// that apart from a reported rate of 0.
	SessionV2Reported bool `json:"-"`
	// contains filtered or unexported fields
}

Account is the plan, limits, prices and capture quota, as the API answers it.

func (Account) MarshalJSON 

func (a Account) MarshalJSON() ([]byte, error)

func (*Account) UnmarshalJSON 

func (a *Account) UnmarshalJSON(b []byte) error

type Avatar 

type Avatar = avatarapi.AvatarDetail

Generated model aliases the commands use.

type AvatarSession 

type AvatarSession = avatarapi.AvatarSessionCreateResponse

Generated model aliases the commands use.

type AvatarSessionInput 

type AvatarSessionInput struct {
	LiveKitURL, LiveKitToken, AgentIdentity string
	MaxDurationSeconds                      *int
	Metadata                                map[string]any
	// WaitJoined returns once the avatar is in the room (minutes on a cold v2 pool).
	WaitJoined bool
}

AvatarSessionInput starts an avatar-only session in your LiveKit room.

type AvatarSummary 

type AvatarSummary = avatarapi.AvatarSummary

Generated model aliases the commands use.

type Balance 

type Balance = avatarapi.AccountBalance

The account reads, as the API answers them (camelCase, microcredits).

type BuildFailedError 

type BuildFailedError struct{ Avatar *Avatar }

BuildFailedError is a build that ended failed or held for moderation.

func (*BuildFailedError) Error 

func (e *BuildFailedError) Error() string

type BuildStage 

type BuildStage = avatarapi.BuildStage

Generated model aliases the commands use.

type Candidate 

type Candidate = avatarapi.Candidate

Generated model aliases the commands use.

func Current 

func Current(cl *CandidateList) []Candidate

Current is the candidates of the avatar's current version (its portrait, voice sample and preview message): the list can also show the serving take of an older version, and with versions=all every older version's takes. A server that does not send `current` is read by generation.

func Previewable 

func Previewable(cl *CandidateList) []Candidate

Previewable is the completed current-version candidates with a preview.

type CandidateList 

type CandidateList = avatarapi.CandidateListResponse

Generated model aliases the commands use.

type CandidatesPage 

type CandidatesPage struct {
	*CandidateList
	Quota *Quota `json:"quota,omitempty"`
}

CandidatesPage is a candidate list with the account's capture quota.

type Client 

type Client struct {
	BaseURL string

	// Sleep is time.Sleep; tests replace it.
	Sleep func(time.Duration)
	// InProgressSleep is the pause before re-sending a request whose first
	// attempt is still running (409 idempotency_key_in_progress).
	InProgressSleep time.Duration
	// MockScenario is sent as X-Mock-Scenario on every request (the local
	// mock's failure injection; production ignores it).
	MockScenario string
	// JoinTimeout bounds each attempt of an avatar-only session start that
	// waits for the join; New sets JoinWaitTimeout.
	JoinTimeout time.Duration
	// WarmingTimeout bounds the resends of an avatar-only start while a v2
	// avatar warms up, counted from the first send. It is a budget of its
	// own: an attempt sent near its end still gets all of JoinTimeout to
	// join. New sets JoinWaitTimeout.
	WarmingTimeout time.Duration
	// OnWarming, when set, hears each wait before an avatar-only start of a
	// v2 avatar is sent again after 503 avatar_warming.
	OnWarming func(wait time.Duration)
	// contains filtered or unexported fields
}

Client is the Avatar API for one key or signed-in user.

func New 

func New(baseURL string, cred Credential, timeout time.Duration) (*Client, error)

New returns a client for baseURL that signs requests with cred.

func (*Client) APIKeys 

func (c *Client) APIKeys(ctx context.Context) ([]Key, error)

APIKeys lists the account's keys, newest first, revoked ones included.

func (*Client) Account 

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

Account is the plan, limits, prices and capture quota.

func (*Client) AddCandidates 

func (c *Client) AddCandidates(ctx context.Context, avatarID string, count int) (*CandidatesPage, error)

AddCandidates captures count (1-10) more candidates. It is sent once: a transport failure is not resent (see sentOnce).

func (*Client) AllCandidates 

func (c *Client) AllCandidates(ctx context.Context, avatarID string) (*CandidatesPage, error)

AllCandidates lists the candidates of every version: an older version's completed take (restorable) can be selected to go back to that version.

func (*Client) Appearance 

func (c *Client) Appearance(ctx context.Context, avatarID string) (*SourceFile, error)

Appearance reads the portrait last given, as a presigned URL.

func (*Client) AvatarSessionStatus 

func (c *Client) AvatarSessionStatus(ctx context.Context, sessionID string) (*SessionStatus, error)

func (*Client) Balance 

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

Balance is the account's credits: what a session can spend now, the buckets, what live sessions hold and what expires when.

func (*Client) Candidates 

func (c *Client) Candidates(ctx context.Context, avatarID string) (*CandidatesPage, error)

Candidates lists the current version's candidates and the serving one.

func (*Client) CheckSize added in v0.10.11 

func (c *Client) CheckSize(ctx context.Context, engine string, r Resolution) error

CheckSize checks a frame size for an engine before it is sent: the engine's rule, then the sizes the account lists for it. A v1 engine is left to the server (which refuses it), and so is the list when the account cannot be read: the server is the authority.

func (*Client) Create 

func (c *Client) Create(ctx context.Context, in CreateInput) (*CreateResult, *Quota, error)

Create creates an avatar. It is sent once: a transport failure is not resent (see sentOnce).

func (*Client) CreateAPIKey 

func (c *Client) CreateAPIKey(ctx context.Context, fields map[string]any) (*KeySecret, error)

CreateAPIKey makes a key; its secret is in the answer, and only there.

func (*Client) CurrentKey 

func (c *Client) CurrentKey(ctx context.Context) (*CurrentUser, error)

CurrentKey is the key making the call: name, scopes, spend cap.

func (*Client) Delete 

func (c *Client) Delete(ctx context.Context, avatarID string) error

func (*Client) DeleteConductor 

func (c *Client) DeleteConductor(ctx context.Context, avatarID string) error

DeleteConductor removes the conductor; removing one that is not set is no error.

func (*Client) DeleteVersion 

func (c *Client) DeleteVersion(ctx context.Context, avatarID, versionID string) (*VersionDeleted, error)

DeleteVersion deletes an older version of a v2 avatar: every take of it and the files only it used. pendingFiles counts what storage could not delete yet; repeating the call retries them.

func (*Client) DesignVoice 

func (c *Client) DesignVoice(ctx context.Context, in DesignVoiceInput, key string) (*DesignedVoices, error)

DesignVoice makes voice previews from a description.

func (*Client) Earnings 

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

Earnings is the creator wallet: what monetized avatars earned, what was paid out, and the balance between them.

func (*Client) EndAvatarSession 

func (c *Client) EndAvatarSession(ctx context.Context, sessionID string) (*SessionEnd, error)

EndAvatarSession is idempotent: ending an ended session reports alreadyEnded.

func (*Client) EndSpeechSession 

func (c *Client) EndSpeechSession(ctx context.Context, sessionID string) (*SpeechSessionEnd, error)

EndSpeechSession ends a speech session. With no connection open it settles at once; with one open the answer is still active, with EndRequestedAt set, and the session settles at its next usage report (within 30 seconds), billed until then.

func (*Client) EnhancePortrait 

func (c *Client) EnhancePortrait(ctx context.Context, in EnhanceInput, key string) (*GeneratedPortraits, error)

EnhancePortrait enhances a photo, or restyles it when a prompt is given. The image is an https URL or upload:<uploadId>.

func (*Client) GenerateClip 

func (c *Client) GenerateClip(ctx context.Context, in ClipInput, key string) (*GeneratedClip, error)

GenerateClip renders a clip from an image and a prompt.

func (*Client) GeneratePortraits 

func (c *Client) GeneratePortraits(ctx context.Context, description, engine, key string) (*GeneratedPortraits, error)

GeneratePortraits makes portraits of an invented character from a description, for engine (v1, v2 or v2hd; empty leaves the API's default).

func (*Client) Get 

func (c *Client) Get(ctx context.Context, avatarID string) (*Avatar, error)

func (*Client) GetClip added in v0.10.12 

func (c *Client) GetClip(ctx context.Context, requestID string) (*ClipStatus, error)

GetClip reads the clip a generate clip call made or is making under requestID. It charges nothing and never starts a render; a request id with no clip is the API's clip_not_found.

func (*Client) GetConductor 

func (c *Client) GetConductor(ctx context.Context, avatarID string) (*Conductor, error)

GetConductor reads the conductor as saved (404 conductor_not_set when none is).

func (*Client) GrantSponsor 

func (c *Client) GrantSponsor(ctx context.Context, avatarID string, microcredits int, key string) (*SponsorGrant, error)

GrantSponsor moves account credits into the pool; a key makes a retry pay once.

func (*Client) Knowledge 

func (c *Client) Knowledge(ctx context.Context, avatarID string) (*Knowledge, error)

Knowledge reads the facts text, the questionnaire answers and the knowledge files (with presigned URLs).

func (*Client) List 

func (c *Client) List(ctx context.Context, limit int, before *time.Time) ([]AvatarSummary, *time.Time, error)

List returns one page, newest first, and the cursor for the next (or nil).

func (*Client) Monetization 

func (c *Client) Monetization(ctx context.Context, avatarID string) (*Monetization, error)

Monetization reads the avatar's monetization eligibility and earnings.

func (*Client) Redeem 

func (c *Client) Redeem(ctx context.Context, code string) (*Redemption, error)

Redeem redeems an invite or credit code for the account: credits, v2 access, or both. Only a signed-in user may; an API key gets 403 login_required.

func (*Client) RemoveThumbnail 

func (c *Client) RemoveThumbnail(ctx context.Context, avatarID string) (*Avatar, error)

RemoveThumbnail removes the Explore thumbnail (Explore shows the portrait).

func (*Client) ReplaceAppearance 

func (c *Client) ReplaceAppearance(ctx context.Context, avatarID, path string) error

ReplaceAppearance sets a new portrait from a local file, an https URL or upload:<uploadId> (v2: new candidates are captured).

func (*Client) ReplaceKnowledge 

func (c *Client) ReplaceKnowledge(ctx context.Context, avatarID string, paths []string) error

ReplaceKnowledge replaces the whole knowledge file set; no paths clears it.

func (*Client) ReplaceVoice 

func (c *Client) ReplaceVoice(ctx context.Context, avatarID, path string) error

ReplaceVoice sets a new voice sample from a local file, an https URL or upload:<uploadId> (v2: re-cloned, new candidates).

func (*Client) RevokeAPIKey 

func (c *Client) RevokeAPIKey(ctx context.Context, keyID string) (*Key, error)

RevokeAPIKey revokes the key for good (again is no error).

func (*Client) RotateAPIKey 

func (c *Client) RotateAPIKey(ctx context.Context, keyID string) (*KeySecret, error)

RotateAPIKey issues a new secret for the key; the old one stops working.

func (*Client) SelectCandidate 

func (c *Client) SelectCandidate(ctx context.Context, avatarID, candidateID string) (*Avatar, error)

SelectCandidate makes a completed candidate live. A completed take of an older version (restorable) goes back to that version: its portrait, voice sample and preview message become the avatar's again.

func (*Client) SetConductor 

func (c *Client) SetConductor(ctx context.Context, avatarID string, body []byte) (*Conductor, error)

SetConductor replaces the avatar's conductor with body (see ConductorBody).

func (*Client) SetThumbnail 

func (c *Client) SetThumbnail(ctx context.Context, avatarID, path string) (*Avatar, error)

SetThumbnail uploads a local image (jpg, png or webp) as the avatar's Explore thumbnail and returns the detail. Nothing is rebuilt.

func (*Client) SpeechSessionStatus 

func (c *Client) SpeechSessionStatus(ctx context.Context, sessionID string) (*SpeechSessionStatus, error)

SpeechSessionStatus reads a speech session's state, end reason and cost.

func (*Client) Sponsor 

func (c *Client) Sponsor(ctx context.Context, avatarID string) (*Sponsor, error)

func (*Client) StartAvatarSession 

func (c *Client) StartAvatarSession(ctx context.Context, avatarID string, in AvatarSessionInput) (*AvatarSession, error)

func (*Client) StartSession 

func (c *Client) StartSession(ctx context.Context, avatarID string, in EmbedSessionInput) (*EmbedSession, error)

StartSession waits for the avatar to join, which can take minutes on a cold pool.

func (*Client) StartSpeechSession 

func (c *Client) StartSpeechSession(ctx context.Context, in SpeechSessionInput) (*SpeechSession, error)

StartSpeechSession reserves a speech session. A transport failure is not resent: a reservation nobody connects to costs nothing and closes by itself, but a resend would hold a second one against the key's limits.

func (*Client) Update 

func (c *Client) Update(ctx context.Context, avatarID string, fields map[string]any) (*Avatar, error)

Update PATCHes exactly the given fields (API names). The API leaves a null or absent field unchanged and removes a value sent empty ("" or []).

func (*Client) UpdateAPIKey 

func (c *Client) UpdateAPIKey(ctx context.Context, keyID string, fields map[string]any) (*Key, error)

UpdateAPIKey changes the fields given (API names; a nil avatarId widens the key to the whole account) and answers the key as saved, whose limits may be below what was sent: the plan's ceilings apply on every edit. A failed edit is safe to send again.

func (*Client) UpdateSponsor 

func (c *Client) UpdateSponsor(ctx context.Context, avatarID string, settings map[string]any) (*Sponsor, error)

UpdateSponsor PATCHes the given settings (API names); nil clears a cap.

func (*Client) UploadPortrait 

func (c *Client) UploadPortrait(ctx context.Context, path string) (string, error)

UploadPortrait sends a local image through the upload API and returns its upload:<uploadId>, for the calls that take no file in their own request.

func (*Client) UploadVoice 

func (c *Client) UploadVoice(ctx context.Context, path string) (string, error)

UploadVoice is UploadPortrait for a local audio file.

func (*Client) Voice 

func (c *Client) Voice(ctx context.Context, avatarID string) (*VoiceFile, error)

Voice reads the voice sample last given, as a presigned URL (its ttsProvider is deprecated and empty).

func (*Client) Wait 

func (c *Client) Wait(ctx context.Context, avatarID string, timeout, interval time.Duration, onUpdate func(*Avatar)) (*Avatar, error)

Wait polls until the avatar settles. onUpdate sees every changed state.

func (*Client) WaitClip added in v0.10.12 

func (c *Client) WaitClip(ctx context.Context, requestID string, timeout, interval time.Duration, onUpdate func(*ClipStatus)) (*ClipStatus, error)

WaitClip reads the clip until it is no longer rendering (ready, expired or stalled), pausing for its retryAfterSeconds between reads (interval when it gives none), for at most timeout. onUpdate, when set, hears each rendering read.

func (*Client) WaitForCandidates 

func (c *Client) WaitForCandidates(ctx context.Context, avatarID string, timeout, interval time.Duration, ids ...string) (*CandidatesPage, error)

WaitForCandidates polls until no current-version candidate is pending. With ids (the captures just requested), it waits until each of them is listed and settled, so a list read before they show up cannot end the wait.

func (*Client) WaitServing 

func (c *Client) WaitServing(ctx context.Context, avatarID, candidateID string, timeout, interval time.Duration) (*Avatar, error)

WaitServing polls until the avatar serves candidateID: the pick is recorded at once, and the avatar serves it once its config is built. It compares the ids rather than trusting a status flag, so an unrelated rebuild does not end it early, and a newer pick (by anyone) ends it with an error. Ids compare as UUIDs, so any spelling of candidateID matches.

func (*Client) WithdrawSponsor 

func (c *Client) WithdrawSponsor(ctx context.Context, avatarID string, microcredits *int) (*SponsorWithdraw, error)

WithdrawSponsor returns unreserved pool credits (all when microcredits is nil).

type ClipInput 

type ClipInput struct {
	Image, Prompt, Audio string
	Duration             int
	// Resolution is the clip's size, one the server offers (nil: the
	// server's default, 480x480 on a server that lists clipSizes).
	Resolution *ClipResolution
	Seed       *int64
}

ClipInput is a clip; Image and Prompt are required, and Duration is required with Audio. Zero values and nil are left for the API's defaults.

type ClipResolution 

type ClipResolution = avatarapi.ClipResolution

ClipResolution is a clip's output size in pixels.

func ParseClipResolution 

func ParseClipResolution(s string) (ClipResolution, error)

ParseClipResolution reads a clip size as WxH (e.g. 1280x720): two positive even numbers. Which sizes a server serves is its own to say (`GET /v1/account` pricing.generation.clipSizes, or clipResolutions on an older server); a size it doesn't serve is refused with its list.

type ClipStatus added in v0.10.12 

type ClipStatus = avatarapi.ClipStatusResponse

ClipStatus is a clip call's status: rendering, ready, expired or stalled.

type Conductor 

type Conductor struct {
	AvatarID    string          `json:"avatarId"`
	Graph       json.RawMessage `json:"graph"`
	SpeakAfterS *float64        `json:"speakAfterS,omitempty"`
	Nodes       int             `json:"nodes"`
	Edges       int             `json:"edges"`
}

Conductor is a v2 avatar's graph conductor as the API returns it. The graph stays raw JSON: it is printed and saved exactly as the API sent it (the generated types would drop null fields and anything they don't name).

type CreateInput 

type CreateInput struct {
	Name           string
	Image          string
	Voice          string
	Knowledge      []string
	Engine         string // "v2" (default), "v1" or "v2hd" (Atmee V2 HD; "v2pro" is read as v2hd)
	Candidates     int    // v2: 1-10; 0 = API default (3)
	SeedSelection  string // v2: "manual" or "auto"
	PreviewMessage string
	Description    string
	Language       string
	Visibility     string
	Previews       *bool
	Facts          string
	Persona        map[string]any // API names: whoPrompt, whatPrompt, greeting, ...
	// Sponsor funds the avatar's pool on create (needs billing:write):
	// microcredits to move in, and the per-session cap.
	SponsorMicrocredits, SponsorMaxPerSession *int
	// RuntimeSeed is the v2 renderer's runtime seed (nil: the default, 42).
	RuntimeSeed *int
	// Resolution is the v2 or V2 HD frame size (nil: the engine's default,
	// 512x512 for v2, 640x640 for V2 HD).
	Resolution *Resolution
}

CreateInput is a create request. Image, Voice and Knowledge are https URLs or upload:<uploadId> (what generation returns), or local paths (all of one kind). Image and Voice are optional: an avatar created without one is a draft, completed later by ReplaceAppearance and ReplaceVoice (a v1 avatar with only a portrait is render-only instead).

func (CreateInput) Manifest 

func (in CreateInput) Manifest() (map[string]any, error)

Manifest is the avatar.json of a create.

type CreateResult 

type CreateResult = avatarapi.AvatarCreateResponse

Generated model aliases the commands use.

type Credential 

type Credential interface {
	Authorize(ctx context.Context, r *http.Request) error
}

Credential signs each request: an API key, or a signed-in user's token.

type CurrentUser 

type CurrentUser = avatarapi.CurrentCaller

The account reads, as the API answers them (camelCase, microcredits).

type DesignVoiceInput 

type DesignVoiceInput struct {
	Description, AvatarName, Language, SampleText string
}

DesignVoiceInput is a voice design; only Description is required.

type DesignedVoices 

type DesignedVoices = avatarapi.DesignedVoicesResponse

Generated portraits and voices. Each comes back as upload:<uploadId>, which a create or a replace takes where it takes an https URL. A clip comes back the same way, with a link to download it.

type Earnings 

type Earnings = avatarapi.AccountEarnings

The account reads, as the API answers them (camelCase, microcredits).

type EmbedSession 

type EmbedSession = avatarapi.EmbedSessionStartResponse

Generated model aliases the commands use.

type EmbedSessionInput 

type EmbedSessionInput struct {
	MaxDurationSeconds *int
	// VisitorID unlocks that visitor's memory across sessions: it MUST be an
	// unguessable id your server derives, never one from the browser.
	VisitorID string
	Language  string
	Metadata  map[string]any
	Location  map[string]any
	// Tools the avatar may call in this conversation (see ParseTools), sent
	// as appTools.tools.
	Tools Tools
	// Instructions is one text for all of Tools, saying how and when the
	// avatar uses them (and any app persona or rules), sent as
	// appTools.instructions; nil leaves it out. It needs Tools.
	Instructions *string
	// NoWelcome starts without the avatar's self-introduction or welcome
	// back, sent as welcome: false; it then waits for the user to speak.
	NoWelcome bool
	// CheckInAfterS is the seconds of silence before the avatar checks in, 0
	// to 3600, 0 for no check-in; nil keeps the default.
	CheckInAfterS *float64
}

EmbedSessionInput starts a full Atmee conversation (our LLM, voice and avatar).

type EnhanceInput added in v0.10.11 

type EnhanceInput struct {
	Image, Prompt, Engine string
	AvatarID              *uuid.UUID
}

EnhanceInput is a photo to enhance; Image is required. Engine and AvatarID are left out of the request when empty.

type Error 

type Error struct {
	Status  int
	Code    string
	Message string
	// Set on 409 (request_in_progress), 429 rate_limited (reason pending_cap)
	// and 503: the seconds from Retry-After.
	Reason     string
	RetryAfter int
	// What a refused share, statement or monetization change found (see
	// ProfileRefusal in the spec): the fields public still needs, the
	// plan's cap on monetized avatars and how many are, the payout
	// account's status, the sponsor pool's credits, the moderation state.
	Missing                 []string
	Cap, MonetizingAvatars  *int
	PayoutsStatus           string
	SponsorPoolMicrocredits int64
	ModerationState         string
}

Error is a non-2xx answer from the Avatar API.

func (*Error) Error 

func (e *Error) Error() string

type GeneratedClip 

type GeneratedClip = avatarapi.GeneratedClipResponse

Generated portraits and voices. Each comes back as upload:<uploadId>, which a create or a replace takes where it takes an https URL. A clip comes back the same way, with a link to download it.

type GeneratedClipBody added in v0.10.12 

type GeneratedClipBody = avatarapi.GeneratedClip

Generated portraits and voices. Each comes back as upload:<uploadId>, which a create or a replace takes where it takes an https URL. A clip comes back the same way, with a link to download it.

type GeneratedPortraits 

type GeneratedPortraits = avatarapi.GeneratedPortraitsResponse

Generated portraits and voices. Each comes back as upload:<uploadId>, which a create or a replace takes where it takes an https URL. A clip comes back the same way, with a link to download it.

type Key 

type Key = avatarapi.ApiKey

API keys, managed by a signed-in user (an API key is answered 403 login_required): the account's keys, and a new key or a new secret, which the API returns only once.

type KeySecret 

type KeySecret = avatarapi.ApiKeySecret

API keys, managed by a signed-in user (an API key is answered 403 login_required): the account's keys, and a new key or a new secret, which the API returns only once.

type Knowledge 

type Knowledge = avatarapi.AvatarKnowledge

Generated model aliases the commands use.

type Monetization 

type Monetization = avatarapi.AvatarMonetization

Generated model aliases the commands use.

type Quota 

type Quota struct {
	Limit     int `json:"limit"`
	Remaining int `json:"remaining"`
}

Quota is the account's capture room from X-RateLimit-* headers: Limit captures may be queued or running at once, and Remaining more fit now.

type Redemption 

type Redemption = avatarapi.CodeRedemption

The account reads, as the API answers them (camelCase, microcredits).

type Resolution 

type Resolution = avatarapi.RenderResolution

Resolution is a v2 frame size in pixels.

func OfferedResolutions added in v0.10.11 

func OfferedResolutions(acct *Account, engine string) []Resolution

OfferedResolutions are the frame sizes the server offers the engine (limits.v2ProResolutions for v2hd, else limits.v2Resolutions), or nil where it lists none (every size the rule allows).

func ParseResolution 

func ParseResolution(s string) (Resolution, error)

ParseResolution reads WxH (e.g. 672x384) and checks it against the largest renderer's rule (V2 HD's); CheckResolutionFor checks an engine's own. Which sizes a deployment offers is the API's to say.

type SessionEnd 

type SessionEnd = avatarapi.AvatarSessionEndResponse

Generated model aliases the commands use.

type SessionStatus 

type SessionStatus = avatarapi.AvatarSessionStatusResponse

Generated model aliases the commands use.

type SourceFile 

type SourceFile = avatarapi.AvatarSourceFile

Generated model aliases the commands use.

type SpeechSession 

type SpeechSession = avatarapi.SpeechSessionCreateResponse

Speech sessions: realtime speech-to-speech conversations over a WebSocket, without video.

type SpeechSessionEnd 

type SpeechSessionEnd = avatarapi.SpeechSessionEndResponse

Speech sessions: realtime speech-to-speech conversations over a WebSocket, without video.

type SpeechSessionInput 

type SpeechSessionInput struct {
	AvatarID           uuid.UUID
	MaxDurationSeconds *int
	Language           string
	// Settings is the pinned settings object (see ParseSpeechSettings), sent
	// as given so fields the CLI does not model reach the API unchanged.
	Settings json.RawMessage
}

SpeechSessionInput is a speech session start; AvatarID is required.

type SpeechSessionStatus 

type SpeechSessionStatus = avatarapi.SpeechSessionStatusResponse

Speech sessions: realtime speech-to-speech conversations over a WebSocket, without video. 

type Sponsor = avatarapi.AvatarSponsor

Generated model aliases the commands use.

type SponsorGrant 

type SponsorGrant = avatarapi.SponsorGrantResponse

Generated model aliases the commands use.

type SponsorWithdraw 

type SponsorWithdraw = avatarapi.SponsorWithdrawResponse

Generated model aliases the commands use.

type Tools 

type Tools []json.RawMessage

Tools is a session's tool list as the caller wrote it: each element is sent unchanged, and the API judges it (400 invalid_tools names the rule).

func ParseTools 

func ParseTools(raw []byte) (Tools, error)

ParseTools checks only the shape a session start needs: a JSON array of objects, each with a string name. Limits, names and values are the API's to check.

type V2ProSizeError added in v0.10.11 

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

V2ProSizeError is a frame size too large for v2 that V2 HD's rule allows. What to do about it depends on the command: a create can choose V2 HD; an existing avatar's engine cannot change.

func (*V2ProSizeError) Error added in v0.10.11 

func (e *V2ProSizeError) Error() string

type VersionDeleted 

type VersionDeleted = avatarapi.VersionDeleteResponse

Generated model aliases the commands use.

type VoiceFile 

type VoiceFile = avatarapi.AvatarVoice

Generated model aliases the commands use.

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.