# Quickstart

Your first generation, from a few lines of code to a finished result.

Use one API to generate images, video and audio with the models available in Fusara. Configure a request in the [playground](/api/models), or start with the example below.

**Base URL:** `https://fusara.ai/api/v3` · JSON requests and responses · API-key authentication

## 1. Get your API key

Open your [Fusara profile](/app/profile), create an API key and keep it on your server. API generations use the same account and balance as Fusara.

Set the key in your terminal. Replace the placeholder with your own key:

```bash
export FUSARA_API_KEY='your-api-key'
```

JavaScript examples run on your server with Node.js. Python examples use `requests`: install it with `python -m pip install requests`. You do not need a Fusara SDK.

## 2. Create your first generation

Send a model ID and the inputs it needs. This example uses Qwen Image 2.1 to create an image. Optional model settings use the model's published defaults.

```bash
curl 'https://fusara.ai/api/v3/run' \
  -H "Authorization: Bearer $FUSARA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "model": "qwen-image21-create",
  "prompt": "A white ceramic lamp on a pale lavender background, soft studio light."
}'
```

To choose a different model or adjust its settings, use the [model playground](/api/models). Its **API code** tab exports the request you configured. Each model's discovery response also includes its exact `request_schema`.

## 3. Keep the run ID

A `202 Accepted` response means the run exists and generation is still in progress. Save its numeric `id`; use it to retrieve the result or match a webhook.

```json
{
  "id": 123456,
  "status": "queued",
  "cost": {
    "unit": "common_fuz",
    "expected": "40.0000",
    "status": "pending"
  }
}
```

The `Location` response header also contains the run's API URL. A submission can return `200` if the run is already terminal, including an idempotent replay. Always inspect `status`.

> Prices, IDs and result URLs in these examples are illustrative. Use the values returned by your own request. [Estimate the current price](/api/billing#estimate-before-you-generate) before generating if you need it.

## 4. Receive your result

You can receive a webhook or check the run yourself. Both return the complete run, including usable output URLs.

### Check the run

Replace `123456` with the ID from your submission:

```bash
curl 'https://fusara.ai/api/v3/run/123456' \
  -H "Authorization: Bearer $FUSARA_API_KEY"
```

While `status` is `queued` or `running`, wait a few seconds before checking again. Stop on `succeeded`, `failed` or `canceled`. A `200` response means the read succeeded; it does not mean the generation succeeded.

```json
{
  "id": 123456,
  "status": "succeeded",
  "cost": {
    "unit": "common_fuz",
    "expected": "40.0000",
    "status": "settled",
    "charged": "40.0000"
  },
  "outputs": [
    {
      "type": "image",
      "media_id": 901,
      "url": "https://media.example/result.png",
      "url_expires_at": "2026-10-25T12:00:00Z"
    }
  ]
}
```

Open or download `outputs[0].url`. Save files you need before `url_expires_at`. Other models can return video, audio, text, JSON or boolean outputs; inspect each output's `type`.

### Or let Fusara send it to you

Add a public HTTPS `webhook_url` when creating the run:

```bash
curl 'https://fusara.ai/api/v3/run' \
  -H "Authorization: Bearer $FUSARA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "model": "qwen-image21-create",
  "prompt": "A white ceramic lamp on a pale lavender background, soft studio light.",
  "webhook_url": "https://your-app.example/webhooks/fusara"
}'
```

Your endpoint receives the complete result above. Save it and respond with `2xx`. **No webhook registration, signature-verification setup or additional result GET is required.** Fusara signs every delivery; verifying that signature is optional and authenticates the sender. Without verification, sender authenticity is unverified.

See [receiving webhooks](/api/webhooks) for failure payloads, duplicate handling and delivery retries.

## Handle a failed generation

A request can be accepted and fail later. A terminal failure appears in the run or webhook, rather than as an HTTP error from the status read:

```json
{
  "id": 123456,
  "status": "failed",
  "cost": {
    "unit": "common_fuz",
    "expected": "40.0000",
    "status": "settled",
    "charged": "0.0000"
  },
  "error": {
    "code": "execution_failed",
    "message": "The run could not be completed."
  }
}
```

Read `error.code` and `error.message`; preserve any usable outputs if present. For a rejected submission or network problem, follow [errors and recovery](/api/errors). Keep your run ID even if your application stops waiting.

## Build your integration

- [Runs & results](/api/runs): polling, history, cancellation and safe submission retries.
- [Media & files](/api/media): image, video and audio inputs; reusing results.
- [Balance & pricing](/api/billing): estimates and final charges.
- [API reference](/api/reference): exact methods, fields and responses.
- [MCP](/api/mcp): connect an assistant to the same models and operations.