Quickstart

Create an API key

Sign in to Havincy and open Profile → API & MCP (havincy.com/profile/developpeurs). Under API keys, name your key, choose its permissions and click Create key.

The full key (hv_live_…) is shown only once. Store it in a secret manager or an environment variable.

export HAVINCY_API_KEY="hv_live_..."

Check your account

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.

Pick a model

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

Generate an image

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
  }'

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);

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"])

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.

Poll longer jobs

Videos usually take longer than the maximum wait (55 s). Poll the asset until its status is completed or failed:

curl https://havincy.com/api/v1/generations/ASSET_ID \
  -H "Authorization: Bearer $HAVINCY_API_KEY"

Get started

MCP for AI agents

Guides

Next steps

Generate videos

Encore effects

Connect ChatGPT or Claude

​Next steps

Generate videos

Encore effects

Connect ChatGPT or Claude

Next steps