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

All TryItOn model endpoints now have dedicated paths for each category:

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

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

Request Examples

cURL

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
         }'

JavaScript

Python

Response Pattern

Initial Response

When you submit a request to /api/v1/tryon/clothes or /api/v1/tryon/hairstyles you'll receive an immediate response with a job ID:

Response Pattern

{
  "id": "64b7f1a9d9a3b8e5c7f9a123",
  "error": null
}

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.

status The current state of your prediction: processing - Model is generating your result completed - Generation finished successfully, output available failed - Generation failed, check error details

Example Status Responses

In Progress:

Response

{
  "id": "64b7f1a9d9a3b8e5c7f9a123",
  "status": "processing",
  "error": null
}

Completed:

Response

{
  "id": "64b7f1a9d9a3b8e5c7f9a123",
  "status": "completed",
  "output": [
    "https://cdn.tryiton.now/dev/tryons/XXX/output.png"
  ],
  "error": null
}

Output Availability Time Limits

• CDN URLs: Available for 72 hours after completion

Learn more in the Data Retention & Privacy section.

Failed:

Response

{
  "id": "64b7f1a9d9a3b8e5c7f9a123",
  "status": "failed",
  "error": {
    "name": "ImageLoadError",
    "message": "Model image is missing."
  }
}

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:

Response

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

Response

// 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:

Code	Error	Cause	Solution
400	BadRequest	Invalid request format	Check request structure and required parameters
401	UnauthorizedAccess	Invalid or missing API key	Verify your API key in the Authorization header
404	NotFound	Resource not found	Check endpoint URL and job ID
429	RateLimitExceeded	Too many requests	Implement request throttling or contact support for higher limit
429	ConcurrencyLimitExceeded	Too many concurrent requests	Wait for current requests to complete
429	OutOfCredits	No API credits remaining	Purchase more credits
500	InternalServerError	Server error	Retry after delay, contact support if persistent

If you’re just getting started and run into issues, you can reach out for help on our Discord server.

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}:

Response

{
  "id": "64b7f1a9d9a3b8e5c7f9a123",
  "status": "failed",
  "error": {
    "name": "ImageLoadError",
    "message": "Model image is missing."
  }
}

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

Endpoint	Try-on Cost Summary
Clothes Tryon	1 per output image
Hairstyle Tryon	1 per output image

Rate Limits

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

Endpoint	Limit
/api/v1/tryon/*	20 requests per 60 seconds
/api/v1/status	300 requests per 60 seconds
/api/v1/credits	300 requests per 60 seconds

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.

Rate Limit Adjustments

Our API rate limits help ensure fair use and prevent abuse. However, we understand that growing applications may need higher limits. If your app’s usage approaches the set limits and it’s justified by your needs, we’re happy to raise them. Please contact us at [email protected] to discuss your requirements.