# REST API quickstart

> Call the same engine over HTTP with curl or any client.

Base URL: `https://api.vincevangen.com`. Every request carries the key:

```http
Authorization: Bearer igk_live_...
```

Create keys in the [dashboard](https://vincevangen.com/app/keys). Interactive OpenAPI docs for the API are at `/docs` on the api
host.

## Generate an image

```bash
curl -sS https://api.vincevangen.com/v1/images/generate \
  -H "Authorization: Bearer $VINCEVANGEN_API_KEY" \
  -H "content-type: application/json" \
  -d '{"prompt":"a red fox in snow, soft morning light, photograph","model":"fast","aspect_ratio":"3:2"}'
```

The response lists assets with an `id` (`a_...`), metadata and a `url` to download the file. Fetch it:

```bash
curl -sS -H "Authorization: Bearer $VINCEVANGEN_API_KEY" \
  "https://api.vincevangen.com/v1/assets/a_XXXX/file" -o fox.png
```

Use `model` values from [Models](https://vincevangen.com/docs/models.md) (`fast`, `default`, `best`, `text`, `premium`, `transparent`).
Raw model ids are refused.

## Routes

| Method and path | Purpose |
|---|---|
| `POST /v1/images/generate` | Generate image variants (`n` up to 8). |
| `POST /v1/images/edit` | Edit or compose from `images` (ids or public URLs). |
| `POST /v1/assets/generate` | A typed asset from a preset (`preset`, `subject`). |
| `POST /v1/images/text` | Draw exact text on an image (free). |
| `POST /v1/videos/generate`, `POST /v1/music` | Start a job; returns `job_id`. |
| `GET /v1/jobs/{id}?wait=60` | Poll a job; `wait` long-polls up to 300 s. |
| `POST /v1/images/judge`, `POST /v1/images/check` | Pass/fail checks on an image. |
| `POST /v1/uploads` | Upload a local image (multipart) and get an asset id. |
| `GET /v1/assets/{id}`, `GET /v1/assets/{id}/file` | Metadata and bytes. |
| `GET /v1/models`, `GET /v1/presets`, `GET /v1/styles` | Discovery. |
| `POST /v1/plan` | Free: what a call would do and cost, without running it. |
| `GET /v1/budget` | Your balance. |

Request bodies mirror the parameters of the matching [MCP tools](https://vincevangen.com/docs/tools.md).

## Jobs (video and music)

```bash
JOB=$(curl -sS https://api.vincevangen.com/v1/music \
  -H "Authorization: Bearer $VINCEVANGEN_API_KEY" -H "content-type: application/json" \
  -d '{"prompt":"lofi hip hop, mellow piano, vinyl crackle","duration":30,"instrumental":true}' | jq -r .job_id)

curl -sS -H "Authorization: Bearer $VINCEVANGEN_API_KEY" "https://api.vincevangen.com/v1/jobs/$JOB?wait=60"
```

If a track sounds thin, muddy or harsh, send the same body with the same `seed` plus `"post":["polish"]`. The polish
step is free, and the cached track is reused, so the generation isn't charged again.

For game or background music, add `"loop":true` (and a `bpm`, so the loop is a whole number of bars). The fade-out is
cut and the end runs back into the start without a click, at the same loudness. The track gets shorter. An mp3 can't
loop without a short gap, so ask for `"format":"wav"` when the loop matters.

## Local files

The server never reads your disk. Upload first, then pass the returned id:

```bash
curl -sS -H "Authorization: Bearer $VINCEVANGEN_API_KEY" -F "file=@logo.png" https://api.vincevangen.com/v1/uploads
```

## Errors

Errors are JSON, `{"error": "...", "code": "..."}`. See [Concepts](https://vincevangen.com/docs/concepts.md#errors) for the codes.