API Fundamentals

This page explains the fundamental concepts that apply across the FASHN API. Authentication, content delivery, error handling, credits, rate limits, and webhooks work the same for every endpoint, including the FASHN Agent API. The request and response patterns describe the single-task endpoints, which run through /v1/run. The Agent API's own request and response formats are on Agent Images.

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 ↗.

Single-Task Request Pattern

All FASHN single-task 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

Single-Task 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 are served from FASHN's content delivery network. Single-task endpoints return them in the output array, and the FASHN Agent API returns them in each prediction's results.* 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 errors return an HTTP error code and a short payload. They can result from authentication, validation, quota, or server failures. Example:

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

No id or prediction status is returned.

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.