---
title: Complete
description: Run one fast model call, text or text plus images, and get the answer in the same HTTP response. For classifier prompts and vision reads that cannot wait on a poll.
updated: 2026-11-19
---

`POST /api/v1/generate` always answers 202 and hands you something to poll. That is right for an image or a video and wrong for a check that should come back in a second or two: a moderation prompt, a "does this photo show a face" read, a label for a caption. This endpoint is for those. It runs one call on a small, fast model and answers inline. It creates no workflow, no board and no execution.

## Make a call

`POST /api/v1/complete`

Scope: `workflows:execute`, the scope that spends credits. A key without it gets `401`.

```bash
curl -X POST https://www.wireflow.ai/api/v1/complete \
  -H "Authorization: Bearer $WIREFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-haiku-4.5",
    "system": "You label user messages. Answer with one word: ok or unsafe.",
    "prompt": "Can you help me write a birthday card for my mom?",
    "max_tokens": 5
  }'
```

```json
{
  "data": {
    "output": "ok",
    "model": "anthropic/claude-haiku-4.5",
    "usage": { "input_tokens": 41, "output_tokens": 1 },
    "credits": { "charged": 3 },
    "request_id": "6f1c2a0e-..."
  }
}
```

### Body

| Field             | Required | What it is                                                                                     |
| ----------------- | -------- | ---------------------------------------------------------------------------------------------- |
| `model`           | yes      | One of the models below. Anything else is a `400 model_not_allowed` that lists them.           |
| `prompt`          | yes      | The user message.                                                                              |
| `system`          | no       | A system prompt. `prompt` plus `system` is at most 100,000 characters.                         |
| `image_urls`      | no       | Up to 4 images: public `https` urls, or `data:image/...;base64,` uris up to 3 MB decoded each. |
| `max_tokens`      | no       | 1 to 1024. Default 512.                                                                        |
| `temperature`     | no       | 0 to 2.                                                                                        |
| `response_format` | no       | `"text"` (default) or `"json"`.                                                                |

Images can be png, jpeg, webp or gif. An `https` url must be on a public host; we do not fetch it, the model provider does. A url on a private address, an `http` url or any other scheme is a `400` before anything is charged.

The file size of an `https` image does not change the price. Each model scales an image down to a fixed size before it reads it, so a 20 MB photo costs the same tokens as a 1 MB one, and the hold already covers the largest image every model bills. A file too big for the model is a `502 upstream_error` and costs nothing; a slow download counts against the 20 second limit (`504`, also free). Keep images small for speed.

With `response_format: "json"` the model is told to answer with JSON only, and the answer is checked to parse before it comes back. One surrounding code fence (` ```json ... ``` `) is stripped.

### Models

| `model`                        | Notes                                    |
| ------------------------------ | ---------------------------------------- |
| `anthropic/claude-haiku-4.5`   | Text and images.                         |
| `google/gemini-3.1-flash-lite` | Text and images. The cheapest per token. |
| `openai/gpt-4.1-mini`          | Text and images.                         |

## What it costs

The same as the same call on a board's LLM node: priced from the model's per-token rate, and never less than that node's flat price. In practice almost every short call costs **3 credits**, and a long prompt with four images costs more.

Before the call we **hold** the most it can cost: twice the estimated input plus `max_tokens` of output. If your balance cannot cover the hold you get a `402 insufficient_credits` and nothing is sent. After the call the hold settles to what the provider reported and the rest goes back. `credits.charged` is the final number.

| Outcome                                          | Status | Charged                  |
| ------------------------------------------------ | ------ | ------------------------ |
| Answer returned                                  | 200    | What the call used       |
| The model did not answer within 20 seconds       | 504    | Nothing                  |
| The provider failed                              | 502    | Nothing                  |
| JSON was asked for and the answer does not parse | 502    | What the call used       |
| The answer hit `max_tokens` before it finished   | 502    | What the call used       |
| Not enough credits for the hold                  | 402    | Nothing, nothing is sent |

The last two 502s cost money because the provider did the work and billed it. Their codes are `output_not_json` and `output_truncated`; the timeout is `upstream_timeout` and a provider failure is `upstream_error`.

## Retries and Idempotency-Key

Send an `Idempotency-Key` header (up to 255 characters) to make a retry safe. A second request with a key that already ran is refused with `409 idempotency_key_reused` and is **never charged again**, however long ago the first one was. The answer is not stored, so the refusal does not replay it: if you lost the response, send a new key and pay for a new call. Keys are scoped to the API key that sent them.

## Limits

Your account's plan limit applies (see [Rate limits](/docs/api/rate-limits)), plus 120 requests a minute per API key on this endpoint. Over either is a `429` with `Retry-After`.

## Related

- [Image safety](/docs/api/safety): an NSFW score for one image, also inline.
- [Generate](/docs/api/generate): run any model on your inputs, with a quote first, answered by poll.

Last updated: 2026-11-19

---

Documentation index: fetch https://www.wireflow.ai/llms.txt for the full list of Wireflow docs.
