> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ekly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Create a key, pick a model, generate an image and download it.

<Steps>
  <Step title="Create an API key">
    In the Ekly app open **Settings → Team → API keys** and choose **Create key**. You need to be an
    organization admin. The secret is shown once; keep it somewhere safe and never commit it.

    ```bash theme={null}
    export EKLY_API_KEY="ek_live_…"
    ```
  </Step>

  <Step title="See which models you can use">
    ```bash theme={null}
    curl https://api.ekly.ai/v1/models \
      -H "Authorization: Bearer $EKLY_API_KEY"
    ```

    Each entry lists the parameters the model accepts and its credit price for your organization.
    The `id` is what you pass as `model` below. `GET /v1/models/{id}` adds a ready-to-send
    `example_request` per mode, so you never have to guess a field name.
  </Step>

  <Step title="Estimate the cost">
    ```bash theme={null}
    curl "https://api.ekly.ai/v1/models/gemini-2.5-flash-image/estimate?generation_count=1" \
      -H "Authorization: Bearer $EKLY_API_KEY"
    ```

    An estimate reserves nothing. It tells you the credits after your discounts and whether your
    balance covers it.
  </Step>

  <Step title="Generate an image">
    ```bash theme={null}
    curl https://api.ekly.ai/v1/images \
      -H "Authorization: Bearer $EKLY_API_KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: article-4821-hero" \
      -d '{
        "prompt": "A red fox resting in autumn leaves, soft morning light",
        "model": "gemini-2.5-flash-image",
        "aspect_ratio": "16:9"
      }'
    ```

    The response comes back immediately with `"status": "pending"` and an `id`. Credits are
    reserved now and settled when the job finishes. The `Idempotency-Key` header means a retry of
    the same request returns the same generation instead of charging twice.
  </Step>

  <Step title="Poll until it finishes">
    ```bash theme={null}
    curl https://api.ekly.ai/v1/generations/$GENERATION_ID \
      -H "Authorization: Bearer $EKLY_API_KEY"
    ```

    Poll every 2–5 seconds. Images usually finish in under a minute, video in a few minutes. When
    `status` is `completed`, `outputs` holds the download URLs; when it is `failed`, `error` says why
    and nothing was charged.
  </Step>

  <Step title="Download the output">
    ```bash theme={null}
    curl -o fox.png "$(curl -s https://api.ekly.ai/v1/generations/$GENERATION_ID \
      -H "Authorization: Bearer $EKLY_API_KEY" | jq -r '.outputs[0].url')"
    ```

    Output URLs are not permanent. Download promptly or copy the file to your own storage.
  </Step>
</Steps>

## Where next

* [Generations](/generations): the lifecycle, polling guidance and idempotency in detail.
* [Uploads](/uploads): register a reference image, video or audio file and get its asset id.
* [Choosing a model](/guides/images): which model fits which job.
* The **API reference** tab has every endpoint with request and response examples in several languages.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.