API Fundamentals

This page covers the key concepts and patterns that apply to all TryItOn API endpoints. Understanding them will help you integrate both current and future endpoints more easily.

Authentication

All API requests require authentication using a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

You can obtain your API key from the Developer API Dashboard.

Request Pattern

Each try-on model has its own dedicated endpoint. They all share the same async flow — submit, get a jobId, poll Job Status:

POST https://tryiton.now/api/v1/tryon/clothes — Clothing

POST https://tryiton.now/api/v1/tryon/hairstyle — Hairstyle

POST https://tryiton.now/api/v1/tryon/tattoo — Tattoo

Request Examples

The quickest way to call the API is an official SDK, which handles auth and the submit-then-poll flow for you. You can also call the endpoint directly with any HTTP client.

import { TryItOn } from "tryiton";

const client = new TryItOn({ apiKey: process.env.TRYITON_API_KEY });

// Each endpoint has its own method, e.g. tryOnClothes / tryOnHairstyle / tryOnTattoo
const jobId = await client.tryOnClothes({ /* endpoint-specific parameters */ });
const output = await client.waitForResult(jobId);

import os
from tryiton import TryItOn

client = TryItOn(api_key=os.environ["TRYITON_API_KEY"])

# Each endpoint has its own method, e.g. try_on_clothes / try_on_hairstyle / try_on_tattoo
job_id = client.try_on_clothes(**params)  # endpoint-specific parameters
output = client.wait_for_result(job_id)

curl -X POST https://tryiton.now/api/v1/tryon/clothes \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -d '{
             // endpoint-specific parameters
         }'

Response Pattern

Initial Response

When you submit a try-on request you'll receive an immediate response with a job ID:

{
  "ok": true,
  "jobId": "64b7f1a9d9a3b8e5c7f9a123"
}

Status Polling

Use the job ID to poll for status and results:

GET https://tryiton.now/api/v1/status/{id}

Response States

Poll for the status of a specific job using its ID.

Example Status Responses

In Progress:

{
  "ok": true,
  "status": "processing",
  "error": null
}

Completed:

{
  "ok": true,
  "status": "completed",
  "output": [
    "https://cdn.tryiton.now/USER_ID/tryons/RESULT.webp"
  ],
  "error": null
}

Failed:

{
  "ok": true,
  "status": "failed",
  "output": [],
  "error": {
    "name": "ProcessingError",
    "message": "Try-on failed. Please try again."
  }
}

Error Handling

There are two distinct types of errors you might encounter when interacting with the API:

API-Level Errors

These errors happen before your request is processed, so no prediction ID is returned. They’re communicated using standard HTTP status codes and include a detailed error message:

// HTTP 401 UnauthorizedAccess
{
  "error": "UnauthorizedAccess",
  "message": "Missing or invalid Authorization header."
}

// HTTP 400 BadRequest
{
  "error": "BadRequest", 
  "message": "Invalid request body"
}

Note that these responses don’t include id or status fields because the request never reached the processing stage. Below is a complete list of possible API-level errors, along with their HTTP status codes, causes, and suggested solutions:

If you’re just getting started and run into issues, you can reach out for help at contact@tryiton.now.

Runtime Errors

These errors occur during model execution, after your request has been successfully submitted and a job ID has been generated. You'll get a 200 HTTP status with status: "failed" when polling /api/v1/status/{id}:

{
  "ok": true,
  "status": "failed",
  "output": [],
  "error": {
    "name": "ProcessingError",
    "message": "Try-on failed. Please try again."
  }
}

Credits & Billing

By default, each endpoint uses 1 credit per output unless specified otherwise on its page. For example, if an endpoint generates multiple images, credits are charged per image. Some endpoints use a variable number of credits depending on their configuration. Credits are not deducted if a prediction fails.

Credit Costs by Endpoint

Rate Limits

These are the default rate limits that apply to all endpoints, unless a specific endpoint’s documentation states otherwise:

Concurrency Limits

The API has a default concurrency limit of 6 requests, meaning you can have up to 6 requests processing at the same time.