# Images · Image API — neuraldeep.tech API

> One section of the machine-readable reference. All sections: https://neuraldeep.tech/llms.txt · everything in one file: https://neuraldeep.tech/llms-full.txt

Base URL: `https://api.neuraldeep.tech/v1`
Auth: `Authorization: Bearer $YOUR_KEY`

Image generation and processing with the same key, endpoints under `/v1/images/*`. Generation and editing run on Qwen-Image on our GPUs in Russia; it understands Russian prompts without translation. Upscale, background removal, enhancement and avatar are separate operations.

Each group has its own quota: generation and editing count separately from processing existing images. The remainder is in `GET /v1/images/quota`. Quota is charged only when the image is ready. A failed task returns it.

**How it works.** Everything is asynchronous, with our own format, not OpenAI's. `POST` creates a task and answers right away with `{"task_uid": "...", "queue_position": N, "eta_sec": N}`. Then poll `GET /v1/images/tasks/{uid}` until `status` becomes `finished` (other values: `queued`, `processing`, `failed`). Fetch the image as a file from `GET /v1/images/tasks/{uid}/result`; until it is ready, this endpoint answers `202` with an empty body. We do not expose storage links.

| endpoint | input | quota |
|---|---|---|
| `POST /v1/images/generate` | JSON `{prompt, options}` | generation |
| `POST /v1/images/edit` | multipart `images[]`, `prompt` | generation |
| `POST /v1/images/upscale` | multipart `image` | processing |
| `POST /v1/images/background/remove` | multipart `image` | processing |
| `POST /v1/images/enhance` | multipart `image` | processing |
| `POST /v1/images/avatar` | multipart `photo`, `gender`, `style` | processing |
| `GET /v1/images/queue` | | current queue |

**Generation parameters**, the `options` field: `width` and `height` (both together), or `aspect_ratio` (`1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `square`), `negative_prompt`, `steps`, `true_cfg_scale`, `seed`, `num_images`, `transparent` (transparent background). Without a size you get a 1312×1312 square. Editing takes the same fields except size: proportions come from the first image.

**Input limits.**

- Output size: at most 1.5 MP. A larger request is not rejected but scaled down keeping proportions, sides rounded down to multiples of 32. Each side up to 2752 px, otherwise `422`.
- `num_images` 1 to 4, `steps` 1 to 50, `true_cfg_scale` 1 to 10, `prompt` up to 4000 characters, `negative_prompt` up to 2000.
- Editing: up to 10 images per request and up to 25 MB for all files together.
- Processing: one file up to 25 MB and up to 4 MP. PNG, JPEG, WebP.
- Queue: one account can have a limited number of tasks waiting or rendering at once. Beyond that you get `429`; wait for your tasks to finish.

```bash
uid=$(curl -s https://api.neuraldeep.tech/v1/images/generate \
  -H "Authorization: Bearer $YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"prompt":"astronaut cat, neon","options":{"width":1024,"height":1024}}' | jq -r .task_uid)

curl https://api.neuraldeep.tech/v1/images/tasks/$uid \
  -H "Authorization: Bearer $YOUR_KEY"

curl https://api.neuraldeep.tech/v1/images/tasks/$uid/result \
  -H "Authorization: Bearer $YOUR_KEY" -o out.png
```

```bash
# edit with words, up to 10 source images
curl https://api.neuraldeep.tech/v1/images/edit \
  -H "Authorization: Bearer $YOUR_KEY" \
  -F "images[]=@photo.jpg" -F "prompt=replace the background with a seashore"

# upscale an existing image
curl https://api.neuraldeep.tech/v1/images/upscale \
  -H "Authorization: Bearer $YOUR_KEY" -F "image=@photo.jpg"
```

```python
import time, httpx

H = {"Authorization": "Bearer $YOUR_KEY"}
job = httpx.post(
    "https://api.neuraldeep.tech/v1/images/generate",
    headers=H, json={"prompt": "a cosmic cat in neon", "options": {"aspect_ratio": "1:1"}},
).json()
uid = job["task_uid"]

# the queue may hold several tasks, keep a timeout on polling
for _ in range(300):
    st = httpx.get(f"https://api.neuraldeep.tech/v1/images/tasks/{uid}", headers=H).json()
    if st["status"] in ("finished", "failed"):
        break
    time.sleep(2)

img = httpx.get(f"https://api.neuraldeep.tech/v1/images/tasks/{uid}/result", headers=H).content
open("out.png", "wb").write(img)
```

**Errors.**

- `400`: empty prompt.
- `402`: the wallet does not have enough money for the operation.
- `404`: the result has expired or there is no image with that index.
- `413`: the file exceeds the limit.
- `422`: a parameter out of range, unknown `aspect_ratio`, more than 10 images in an edit, the file is not an image.
- `429`: the quota is used up (`quota_exceeded` body, see [getting started](https://neuraldeep.tech/docs/start.md)) or too many of your tasks are in the queue.
- `503`: generation or processing is temporarily unavailable, retry later.