tryiton

README

TryItOn Go SDK — AI Virtual Try-On API

Official Go client for the TryItOn virtual try-on API. Add photoreal AI virtual try-on for clothing, accessories, hairstyles, and tattoos to your Go application with a few lines of code.

• Virtual clothing try-on and accessory try-on (eyewear, footwear, headwear, jewelry)
• Hairstyle and tattoo try-on
• Standard library only (no dependencies), context-aware, with a built-in job polling helper

Full API reference: docs.tryiton.now · Get an API key: tryiton.now/app/developer

Installation

go get github.com/tryiton-now/tryiton-go

Requires Go 1.20 or later.

Quickstart: run a virtual try-on

Submit a garment and a model photo, then wait for the generated result image.

package main

import (
	"context"
	"fmt"
	"log"
	"os"
	"time"

	tryiton "github.com/tryiton-now/tryiton-go"
)

func main() {
	client, err := tryiton.New(os.Getenv("TRYITON_API_KEY"))
	if err != nil {
		log.Fatal(err)
	}

	ctx := context.Background()

	// Submit a clothing try-on
	jobID, err := client.TryOnClothes(ctx, tryiton.ClothesParams{
		ModelImage:   "https://example.com/model.jpg",
		GarmentImage: "https://example.com/tshirt.jpg",
		Category:     "clothing",
		Subcategory:  "tops",
	})
	if err != nil {
		log.Fatal(err)
	}

	// Poll until the job completes and return the output image URL(s)
	urls, err := client.WaitForResult(ctx, jobID, 2*time.Second)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(urls[0]) // CDN URL, available for 72 hours
}

Image inputs accept a public URL or a base64 data URL (data:image/png;base64,...).

Core parameters

TryOnClothes covers clothing and accessory try-on. The most important fields of ClothesParams:

Field	Type	Required	Description
ModelImage	string	Yes	URL or base64 data URL of the person.
GarmentImage	string	Yes	URL or base64 data URL of the garment or accessory.
Category	string	No	Item type: auto, clothing, eyewear, footwear, headwear, jewelry, accessories, or others. auto detects it for you.
Subcategory	string	No	Required for clothing (tops, bottoms, dresses), jewelry, and accessories.

Additional clothing options (Mode, NumSamples, OutputFormat, Seed) are documented in the API reference.

Other endpoints

// Hairstyle try-on (see tryiton.Haircuts for all supported values)
client.TryOnHairstyle(ctx, tryiton.HairstyleParams{FaceImage: faceURL, Haircut: "BuzzCut", HairColor: "ash blonde"})

// Tattoo try-on
client.TryOnTattoo(ctx, tryiton.TattooParams{BodyImage: bodyURL, DesignImage: designURL, Placement: "on the right forearm, small"})

// Poll a job manually, or check your credit balance
status, _ := client.GetStatus(ctx, jobID)  // *Status{ Status, Output, Error }
credits, _ := client.GetCredits(ctx)        // *Credits{ OnDemand, Subscription, Purchased, Reserved }

Error handling

API and job failures are returned as *tryiton.Error, which carries the HTTP status code and the API error name.

urls, err := client.WaitForResult(ctx, jobID, 2*time.Second)
if err != nil {
	var apiErr *tryiton.Error
	if errors.As(err, &apiErr) {
		fmt.Println(apiErr.Status, apiErr.Name, apiErr.Message) // e.g. 429, "OutOfCredits"
	}
}

Notes

• Output image URLs expire 72 hours after completion. Download any results you want to keep.
• Failed jobs are never charged.

Documentation

Full documentation, parameter reference, and guides: docs.tryiton.now

License

MIT

Documentation

Overview

Package tryiton is the official Go SDK for the TryItOn virtual try-on API.

See https://docs.tryiton.now for the full API reference.

Index

• Constants
• Variables
• type Client
  • func New(apiKey string, opts ...Option) (*Client, error)
  • func (c *Client) GetCredits(ctx context.Context) (*Credits, error)
  • func (c *Client) GetStatus(ctx context.Context, jobID string) (*Status, error)
  • func (c *Client) TryOnClothes(ctx context.Context, p ClothesParams) (string, error)
  • func (c *Client) TryOnHairstyle(ctx context.Context, p HairstyleParams) (string, error)
  • func (c *Client) TryOnTattoo(ctx context.Context, p TattooParams) (string, error)
  • func (c *Client) WaitForResult(ctx context.Context, jobID string, pollInterval time.Duration) ([]string, error)
• type ClothesParams
• type Credits
• type Error
  • func (e *Error) Error() string
• type HairstyleParams
• type JobError
• type Option
  • func WithBaseURL(u string) Option
  • func WithHTTPClient(h *http.Client) Option
• type Status
• type TattooParams

Constants

const DefaultBaseURL = "https://tryiton.now/api/v1"

DefaultBaseURL is the production API base URL.

Variables

var Haircuts = []string{
	"Afro", "BobCut", "BowlCut", "BoxBraids", "BuzzCut", "Chignon", "CombOver",
	"CornrowBraids", "CurlyBob", "CurlyShag", "DoubleBun", "Dreadlocks", "FauxHawk",
	"FishtailBraid", "LongCurly", "LongHairTiedUp", "LongHimeCut", "LongStraight",
	"LongTwintails", "LongWavy", "LongWavyCurtainBangs", "ManBun", "MessyTousled",
	"PixieCut", "Pompadour", "Ponytail", "ShortCurlyPixie", "ShortTwintails",
	"ShoulderLengthHair", "Spiky", "TexturedFringe", "TwinBraids", "Updo", "WavyShag",
}

Haircuts lists the supported `haircut` values for hairstyle try-on.

Types

type Client

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

Client is a TryItOn API client. Create one with New.

func New

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

New creates a Client with the given API key.

func (*Client) GetCredits

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

GetCredits fetches your current credit balance.

func (*Client) GetStatus

func (c *Client) GetStatus(ctx context.Context, jobID string) (*Status, error)

GetStatus fetches the current status of a job.

func (*Client) TryOnClothes

func (c *Client) TryOnClothes(ctx context.Context, p ClothesParams) (string, error)

TryOnClothes puts a garment or accessory on a person and returns the job id.

func (*Client) TryOnHairstyle

func (c *Client) TryOnHairstyle(ctx context.Context, p HairstyleParams) (string, error)

TryOnHairstyle restyles a person's hair and returns the job id.

func (*Client) TryOnTattoo

func (c *Client) TryOnTattoo(ctx context.Context, p TattooParams) (string, error)

TryOnTattoo inks a design onto skin and returns the job id.

func (*Client) WaitForResult

func (c *Client) WaitForResult(ctx context.Context, jobID string, pollInterval time.Duration) ([]string, error)

WaitForResult polls a job until it completes, then returns the output image URLs. It returns an *Error if the job fails or the context is cancelled.

type ClothesParams

type ClothesParams struct {
	ModelImage       string `json:"model_image"`
	GarmentImage     string `json:"garment_image"`
	Category         string `json:"category,omitempty"`
	Subcategory      string `json:"subcategory,omitempty"`
	Mode             string `json:"mode,omitempty"`
	NumSamples       int    `json:"num_samples,omitempty"`
	OutputFormat     string `json:"output_format,omitempty"`
	Seed             int    `json:"seed,omitempty"`
	SegmentationFree *bool  `json:"segmentation_free,omitempty"`
	GarmentPhotoType string `json:"garment_photo_type,omitempty"`
	ModerationLevel  string `json:"moderation_level,omitempty"`
}

ClothesParams are the inputs for a clothing/accessory try-on. Image fields accept a public URL or a base64 data URL. Category is one of: auto, clothing, eyewear, footwear, headwear, jewelry, accessories, others. clothing, jewelry, and accessories require a Subcategory.

type Credits

type Credits struct {
	OnDemand     int `json:"on_demand"`
	Subscription int `json:"subscription"`
	Purchased    int `json:"purchased"`
	Reserved     int `json:"reserved"`
}

Credits is your credit balance.

type Error

type Error struct {
	// Status is the HTTP status code, or 0 for a runtime job failure.
	Status int
	// Name is the API error name, e.g. "OutOfCredits" or "ProcessingError".
	Name string
	// Message is the human-readable message.
	Message string
}

Error is returned for API-level errors and runtime (job) failures.

func (*Error) Error

func (e *Error) Error() string

type HairstyleParams

type HairstyleParams struct {
	FaceImage string `json:"face_image"`
	Haircut   string `json:"haircut"`
	HairColor string `json:"hair_color,omitempty"`
}

HairstyleParams are the inputs for a hairstyle try-on.

type JobError

type JobError struct {
	Name    string `json:"name"`
	Message string `json:"message"`
}

JobError describes a runtime job failure.

type Option

type Option func(*Client)

Option configures a Client.

func WithBaseURL

func WithBaseURL(u string) Option

WithBaseURL overrides the API base URL.

func WithHTTPClient

func WithHTTPClient(h *http.Client) Option

WithHTTPClient supplies a custom *http.Client (e.g. with a timeout).

type Status

type Status struct {
	Status string    `json:"status"` // "processing" | "completed" | "failed"
	Output []string  `json:"output"`
	Error  *JobError `json:"error"`
}

Status is a job's status snapshot.

type TattooParams

type TattooParams struct {
	BodyImage   string `json:"body_image"`
	DesignImage string `json:"design_image"`
	Placement   string `json:"placement,omitempty"`
}

TattooParams are the inputs for a tattoo try-on.