API Fundamentals

This page explains the fundamental concepts and patterns that are consistent across all FASHN API endpoints. Understanding these concepts will help you integrate any current or future endpoint.

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 FASHN model endpoints follow a consistent request pattern to the same /v1/run endpoint:

curl -X POST https://api.fashn.ai/v1/run \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -d '{
           "model_name": "endpoint-specific-model-name",
           "inputs": {
             // endpoint-specific parameters
           }
         }'

Universal Request Properties

Response Pattern

Initial Response

When you submit a request to /v1/run, you'll receive an immediate response with a prediction ID:

{
  "id": "123a87r9-4129-4bb3-be18-9c9fb5bd7fc1-u1",
  "error": null
}

Status Polling

Use the prediction ID to poll for status and results:

Response States

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

Response Headers

• x-fashn-credits-used: Indicates how many credits were consumed for that prediction.

Example Status Responses

In Progress:

{
  "id": "123a87r9-4129-4bb3-be18-9c9fb5bd7fc1-u1",
  "status": "processing",
  "error": null
}

Completed:

{
  "id": "123a87r9-4129-4bb3-be18-9c9fb5bd7fc1-u1",
  "status": "completed",
  "output": [
    "https://cdn.fashn.ai/123a87r9-4129-4bb3-be18-9c9fb5bd7fc1-u1/output_0.png"
  ],
  "error": null
}

Failed:

{
  "id": "123a87r9-4129-4bb3-be18-9c9fb5bd7fc1-u1",
  "status": "failed",
  "error": {
    "name": "ImageLoadError",
    "message": "Error loading model image: Invalid URL format"
  }
}

Content Delivery

By default, output URLs returned in the output array are served from FASHN's content delivery network.* Depending on routing, outputs may be delivered from either of these domains:

• https://cdn.fashn.ai/...
• https://media.fashn.ai/...

Both are official FASHN delivery domains and are interchangeable. The outputs for a given prediction may be served from either one, and the serving domain can differ between requests. API outputs are scheduled for expiry after three days.

Error Handling

At a high level there are two kinds of errors you may see. For detailed guidance and the full list of error codes, see the Error Handling page.

API-Level Errors

These are request validation or auth failures that happen before a prediction ID is issued. They return an HTTP error code and a short payload. Example:

// HTTP 401 UnauthorizedAccess
{
  "error": "UnauthorizedAccess",
  "message": "Unauthorized: Invalid token"
}

No id or status is returned because the request never entered processing.

Runtime Errors

These happen during model execution after a prediction ID was returned. You’ll see them when polling /v1/status/{id} with status: "failed". Some runtime errors are common across endpoints (for example, malformed image URLs), while others are endpoint-specific validations; see Error Handling for details. Example:

{
  "id": "123a87r9-4129-4bb3-be18-9c9fb5bd7fc1-u1",
  "status": "failed",
  "error": {
    "name": "ImageLoadError",
    "message": "Error loading model image: Invalid URL format"
  }
}

Credits & Pricing

Credits are the billing unit for all FASHN API endpoints. Pricing is charged per successful output, and the exact cost depends on the endpoint and selected options.

Billing Basics

• Failed predictions do not consume credits.
• Pricing is applied per output. If you request multiple outputs, the per-output cost is multiplied accordingly.
• Depending on the endpoint, pricing may be fixed per output, vary based on parameters such as resolution, generation_mode, or duration, or include optional surcharges such as face_reference.

Each endpoint page includes its own Credit Cost section. For a centralized overview, see the API pricing guide: Credit Costs ↗.

Rate Limits

These are the default rate limits that apply to all endpoints unless stated otherwise in the specific endpoint documentation:

Concurrency Limits

The API has a default concurrency limit of 6 requests per limit. This means you can have up to 6 concurrent requests being processed at any given time.

Endpoint Lifecycle

Every FASHN API model has a lifecycle stage that describes its stability and integration guidance. See Model Lifecycle for stage definitions, release dates, and the current status of every model.

Webhooks

Instead of polling for status, you can configure webhooks to receive notifications when predictions complete. See the Webhooks Guide for setup instructions.