# Concepts

> Aliases, credits, files, jobs and the error codes.

## Aliases, not model names

You ask for `fast`, `default`, `best`, `text`, `premium` or `transparent` (and `kind:alias` forms such as
`video:best`). The service maps each alias to a model we have checked for commercial use of its output.
Raw model ids are refused. See [Models](https://vincevangen.com/docs/models.md) for the current lineup and [Licences](https://vincevangen.com/docs/licences.md)
for the terms.

The normal call is one final on `default`: a brief that names the subject, medium, lighting and composition
needs no drafts. When you want options, or the brief is open, draft four on `fast` (`n=4`, billed per sheet
of two), look at the contact sheet, then finish the pick with `from_draft` set to its id on `default` or
`best`. That is an edit of the draft (priced as one, so it costs more than a plain final) and the final is the
same picture. Drafts pay off when you would otherwise make two or more finals. A seed only repeats an image
on the same model; the same seed on another tier gives a different one.

## Credits

Calls are priced in credits; 1 credit is worth $0.01. Credits you buy do not expire. A tool result shows
what a call cost in credits, and `GET /v1/budget` (or the dashboard) shows your balance. Current prices and
packs are on the [pricing page](https://vincevangen.com/pricing.md).

A call that would cost more than your balance is refused before anything runs. A very expensive call can
also ask for confirmation first: the refusal names an amount, and you resend with `confirm_spend` once you
agree. Agents are told to ask you before doing that.

## Files and previews

Every result has an id (`a_...`), metadata and a download link. Results include one small preview (a numbered
contact sheet when you asked for several variants), never the full image. Ask for full size with
[`vvgen_get_file`](https://vincevangen.com/docs/tools.md#vvgen_get_file) or `GET /v1/assets/{id}/file`.

Output files are never overwritten on your machine; a repeat becomes `-v2`.

## Inputs

Anywhere an image is accepted you can pass a public `https://` URL or an asset id from an earlier call. The
server cannot read your disk. For a local file call [`vvgen_create_upload`](https://vincevangen.com/docs/tools.md#vvgen_create_upload)
(MCP) or `POST /v1/uploads` (REST) and use the returned id. Uploads are images or audio, up to 25 MB. In the Claude
app, Claude uploads a photo you attach itself when its sandbox may reach `api.vincevangen.com`
([how](https://vincevangen.com/docs/quickstart/claude.md#your-own-photos)); otherwise it gives you the upload link to open in your browser and
pick the file, and gets the id when you're done.

## Jobs

Video and music take seconds to minutes. Those calls return a `job_id`; poll with
[`vvgen_get_job`](https://vincevangen.com/docs/tools.md#vvgen_get_job) or `GET /v1/jobs/{id}?wait=60`.

## Provenance

Every output records its prompt, seed, alias, model, references and licence. The record is embedded in PNG,
JPEG and WebP files and returned in the asset metadata. `vvgen provenance <file>` verifies a download.

## Errors

JSON body `{"error": "...", "code": "..."}`; MCP tools return the same text as a readable tool error.

| HTTP | `code` | Meaning |
|---|---|---|
| 401 | `invalid_key` | Missing, unknown or revoked key. |
| 402 | `insufficient_credits` | Balance is below the estimate. The body has `balance`, `estimate` and `top_up_url`. |
| 403 | `account_suspended` | The account is not active. |
| 422 | `content_policy` | The prompt or an input image was refused. |
| 424 | `provider_key_rejected` / `provider_balance` | Only if your account uses its own DeepInfra key: DeepInfra refused the key, or its DeepInfra balance is empty. Fix it in Settings or at deepinfra.com. |
| 428 | `confirm_spend` | Resend with `confirm_spend` set to the amount the refusal named, after the user agrees. |
| 429 | `rate_limited` | Slow down; honour the `Retry-After` header. |
| 503 | `service_capacity` | The service is temporarily at capacity; retry later. |

## Signing in

The sign-in page is run by WorkOS. What two of its messages mean:

- "This email is not available": that address already has a login, maybe from a sign-up you didn't finish. Use
  [Sign in](https://vincevangen.com/login) instead; it sends a code if the address isn't verified yet. Forgot the password: reset it there.
- "Too many requests" (sometimes shown as raw text): too many tries in a short time. Wait a minute, then start again
  from [vincevangen.com/login](https://vincevangen.com/login).

Each inbox can have one account. If you signed up before with another form of the same address (a `+tag`, or dots in
a Gmail address), sign in with that one.