# 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 <a href="#authentication" id="authentication"></a>

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](https://tryiton.now/app/developer).

#### Request Pattern <a href="#request-pattern" id="request-pattern"></a>

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**

{% tabs %}
{% tab title="cURL" %}

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

{% endtab %}

{% tab title="JavaScript" %}

```python
fetch('https://tryiton.now/api/v1/tryon/clothes', {
  method: 'POST',
  body: JSON.stringify({
      // endpoint-specific parameters
  }),
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  }
});
```

{% endtab %}

{% tab title="Python" %}

```python
import requests
 
response = requests.post(
  "https://tryiton.now/api/v1/tryon/clothes",
  headers={
    "Authorization": "Bearer YOUR_API_KEY", 
    "Content-Type": "application/json"
  },
  json={
      // endpoint-specific parameters
  }
)
```

{% endtab %}
{% endtabs %}

### Response Pattern <a href="#response-pattern" id="response-pattern"></a>

#### Initial Response <a href="#initial-response" id="initial-response"></a>

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:

<details>

<summary>Response Pattern</summary>

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

</details>

#### Status Polling <a href="#status-polling" id="status-polling"></a>

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.

|                                                                                                                                                                                                                                                                                                                             |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <p><strong><code>status</code></strong></p><p>The current state of your prediction:</p><ul><li><code>processing</code> - Model is generating your result</li><li><code>completed</code> - Generation finished successfully, output available</li><li><code>failed</code> - Generation failed, check error details</li></ul> |

**Example Status Responses**

**In Progress:**

<details>

<summary>Response</summary>

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

</details>

**Completed:**

<details>

<summary>Response</summary>

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

</details>

{% hint style="info" %}
**Output Availability Time Limits**

* **CDN URLs**: Available for **72 hours** after completion

Learn more in the [Data Retention & Privacy](/api-overview/data-retention-and-privacy.md) section.
{% endhint %}

**Failed:**

<details>

<summary>Response</summary>

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

</details>

### Error Handling <a href="#error-handling" id="error-handling"></a>

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

#### API-Level Errors <a href="#api-level-errors" id="api-level-errors"></a>

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:

<details>

<summary>Response</summary>

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

</details>

<details>

<summary>Response</summary>

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

</details>

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:

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

If you’re just getting started and run into issues, you can reach out for help on our [Discord server](https://discord.gg/CrMq9WdHdt).

#### Runtime Errors <a href="#runtime-errors" id="runtime-errors"></a>

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

<details>

<summary>Response</summary>

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

</details>

### Credits & Billing <a href="#credits--billing" id="credits--billing"></a>

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 <a href="#credit-costs-by-endpoint" id="credit-costs-by-endpoint"></a>

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

### Rate Limits <a href="#rate-limits" id="rate-limits"></a>

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 <a href="#concurrency-limits" id="concurrency-limits"></a>

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

{% hint style="info" %}
**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 <contact@tryiton.now> to discuss your requirements.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tryiton.now/api-overview/api-fundamentals.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.