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

# Quickstart

> Create an API key and generate your first image.

<Steps>
  <Step title="Create an API key">
    Sign in to Havincy and open **Profile → API & MCP** ([havincy.com/profile/developpeurs](https://havincy.com/profile/developpeurs)). Under **API keys**, name your key, choose its permissions and click **Create key**.

    <Warning>The full key (`hv_live_…`) is shown **only once**. Store it in a secret manager or an environment variable.</Warning>

    ```bash theme={null}
    export HAVINCY_API_KEY="hv_live_..."
    ```
  </Step>

  <Step title="Check your account">
    ```bash theme={null}
    curl https://havincy.com/api/v1/account \
      -H "Authorization: Bearer $HAVINCY_API_KEY"
    ```

    The response contains your workspace, your **credit balance** and the permissions of the key.
  </Step>

  <Step title="Pick a model">
    ```bash theme={null}
    curl "https://havincy.com/api/v1/models?modality=image" \
      -H "Authorization: Bearer $HAVINCY_API_KEY"
    ```

    Each model lists its `id`, its cost (`credits_per_output`) and its valid options (aspect ratios, resolutions, durations, voices).
  </Step>

  <Step title="Generate an image">
    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST https://havincy.com/api/v1/generations \
        -H "Authorization: Bearer $HAVINCY_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "modality": "image",
          "model_id": "fal-nano-banana-2",
          "prompt": "A cat astronaut floating above Paris, watercolor",
          "aspect_ratio": "1:1",
          "wait_seconds": 40
        }'
      ```

      ```javascript Node.js theme={null}
      const res = await fetch("https://havincy.com/api/v1/generations", {
        method: "POST",
        headers: {
          Authorization: `Bearer ${process.env.HAVINCY_API_KEY}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          modality: "image",
          model_id: "fal-nano-banana-2",
          prompt: "A cat astronaut floating above Paris, watercolor",
          aspect_ratio: "1:1",
          wait_seconds: 40,
        }),
      });
      const generation = await res.json();
      console.log(generation.assets[0].url);
      ```

      ```python Python theme={null}
      import os, requests

      res = requests.post(
          "https://havincy.com/api/v1/generations",
          headers={"Authorization": f"Bearer {os.environ['HAVINCY_API_KEY']}"},
          json={
              "modality": "image",
              "model_id": "fal-nano-banana-2",
              "prompt": "A cat astronaut floating above Paris, watercolor",
              "aspect_ratio": "1:1",
              "wait_seconds": 40,
          },
      )
      print(res.json()["assets"][0]["url"])
      ```
    </CodeGroup>

    With `wait_seconds`, the request waits up to that many seconds for the result. When the asset is `completed`, its `url` points to the hosted file.
  </Step>

  <Step title="Poll longer jobs">
    Videos usually take longer than the maximum wait (55 s). Poll the asset until its `status` is `completed` or `failed`:

    ```bash theme={null}
    curl https://havincy.com/api/v1/generations/ASSET_ID \
      -H "Authorization: Bearer $HAVINCY_API_KEY"
    ```

    See [Async generation and polling](/guides/async-and-polling).
  </Step>
</Steps>

## Next steps

<CardGroup cols={3}>
  <Card title="Generate videos" icon="film" href="/guides/generate-videos" />

  <Card title="Encore effects" icon="sparkles" href="/guides/encore-effects" />

  <Card title="Connect ChatGPT or Claude" icon="plug" href="/mcp/overview" />
</CardGroup>


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