# imageat API

Generate and edit images, generate videos and speech, call every catalog LLM, and run published workflows from your own application. AI agents (Claude Code, Claude, ChatGPT, Codex, Cursor, Gemini CLI, VS Code, Windsurf, OpenCode, Grok Bot, OpenClaw, Hermes and any other MCP client) can connect to the MCP server at https://mcp.imageat.com/mcp instead.

**Base URL:** `https://api.imageat.com/v1`

---

## Introduction

The Workflow API lets you trigger a published imageat workflow with a single HTTP request, poll for completion, and receive CDN-hosted outputs. Every run is metered and billed against the API key's owning account.

A typical integration is three calls: `POST` to create a run, `GET` (or subscribe via SSE) to track progress, and then read CDN URLs from the final response.

---

## Authentication

All requests are authenticated with an API key sent as a Bearer token. Create keys from your Projects page. Keys start with `iat_live_` (production) or `iat_test_` (sandbox).

```
Authorization: Bearer iat_live_xxxxxxxxxxxxxxxx
```

Keep your API key on the server. Never expose it in client-side code or commit it to source control. Revoke and rotate from the Projects page if a key is exposed.

---

## API pricing

Public API requests spend your website credits at website rates first, then a prepaid USD API balance at the prices below. Current starting prices:

| model | starts at | minimum configuration |
|-------|-----------|-----------------------|
| nano-banana-2-lite | $0.08/image | 512px |
| nano-banana-2.1 | $0.16/image | 1K |
| krea-3 | $0.06/image | 1K, no references (+$0.06 per reference at 1K) |
| nano-banana-2 | $0.16/image | 1K |
| nano-banana-pro | $0.40/image | 1K |
| midjourney-v8 (image) | $0.18/run of 4 images | 1K ($0.26 at 2K HD) |
| gpt-image-2.6 | $0.02/image | low quality, 1K (GIF: $0.03 low, $0.07 medium per animation) |
| gpt-image-2.5 | $0.02/image | low quality, 1K |
| gpt-image-2 | $0.02/image | low quality, 1K |
| kling-image-4 | $0.13/image | 1K or 2K, no references ($0.19 at 4K; each reference image adds about $0.01) |
| seedream-5.5 | $0.06/image | 1K, no references ($0.09 at 2K; each reference image adds about $0.03) |
| seedream-5.0-pro | $0.14/image | 1K |
| nano-banana | $0.16/image | 1K |
| krea-2-medium | $0.07/image | one image per request |
| krea-2-large | $0.13/image | one image per request |
| gemini-omni-12 | $0.055/second | 360p, 3s minimum ($0.16/s 720p, $0.25/s 1080p, $0.49/s 4K; native audio) |
| kling4 | $0.32/second | 720p, 3s minimum ($0.47/s 1080p; edit $0.38/$0.57 per source second) |
| flux3-max | $1.71/video | 5s, 720p ($0.34/s 720p, $0.58/s 1080p) |
| wan3 | $0.20/video | 2s, 480p ($0.10/s 480p, $0.20/s 720p, $0.40/s 1080p) |
| minimax-h3-max | $0.50/video | 5s, 480p |
| seedance25 | $0.83/video | 4s, 480p |
| seedance25-flash | $0.57/video | 4s, 480p |
| midjourney-v8 (video) | $0.18/run of 4 videos | 4 × 5s, 480p ($0.52 at 720p) |
| pixverse | $0.09/second | 720p, audio off |
| veo (default) | $1.20/video | 4s, 720p, audio off |
| veo-lite | $0.40/video | 4s, 720p |
| sora | $0.80/video | 4s, 720p |
| kling | $0.70/video | 5s, audio off |
| kling3 | $0.34/second | 720p, audio off |
| kling3-omni | $0.42/second | 720p, audio off |
| grok | $0.10/second | 480p |
| grok-1-5 | $0.17/second | 480p, image-to-video |
| seedance2 | $1.08/video | 4s, 480p |
| seedance2-mini | $0.36/video | 5s, 480p |
| gemini-omni | $2.12/video | 5s, 720p |
| happyhorse / happyhorse-ref | $1.40/video | 5s, 720p |
| flux3 | $1.70/video | 5s, 720p |
| image edits (POST /v1/edit) | $0.01–$0.63/request | see Edit API |
| elevenlabs-tts | $0.30/1K characters | POST /v1/audio/speech |
| gemini-tts | $0.10/1K characters | POST /v1/audio/speech |
| sound-effects | $0.10/started 10 seconds | POST /v1/audio/sound-effects |
| ffmpeg | $0.01/started minute, $0.03 minimum | POST /v1/ffmpeg/process |
| Qwen 3.8 family | $0.00117/second | billed by model execution time |
| Other catalog LLMs | usage-based | final charge in billing.amount_usd |

See https://imageat.com/api-pricing for the current pricing overview. Image cost scales with output count, resolution, and quality. Video cost scales with duration, resolution, audio, and mode.

---

## Image API

All image models use `POST /v1/images`. Add public or base64 image URLs in `images` for reference-guided editing.

| Models page entry | API model value | guide |
|-------------------|-----------------|-------|
| Nano Banana Pro | nano-banana-pro | High-fidelity generation/editing, up to 4K |
| Nano Banana 2.1 | nano-banana-2.1 | Google's newest Nano Banana, up to 4K; extreme ratios (8:1 to 1:8) and "auto"; up to 14 reference images; enableWebSearch for grounding |
| Krea 3 | krea-3 | Aesthetic generation with prompt expansion and faithful edits; 1K or 2K (4K renders at 2K); up to 4 reference images, each billed |
| Nano Banana 2 | nano-banana-2 | Fast generation/editing, up to 4K |
| GPT Image 2.6 | gpt-image-2.6 or gpt-image-2.6-sunburst | Same controls as GPT Image 2.5, plus outputFormat: "gif" for one animated GIF; gifFrames 2–16 (default 9) and gifFrameMs 20–2000 (default 160); a GIF is priced as one 4K image |
| GPT Image 2.5 | gpt-image-2.5 or gpt-image-2.5-sunburst | Add quality: low, medium, high, xhigh, or max; transparentBackground for cut-outs; up to 16 reference images |
| Midjourney V8 | midjourney-v8 | Midjourney V8.2; 4 images per run (read `urls`), 1K or 2K HD; see the Midjourney V8 section below |
| GPT Image 2 | gpt-image-2 | Add quality: low, medium, or high |
| Kling Image 4.0 | kling-image-4 | Kling's newest; 2K or 4K (1K requests render at 2K), up to 10 reference images |
| Seedream 5.5 | seedream-5.5 | ByteDance's newest; 1K or 2K, up to 10 reference images for edits |
| Seedream 5 | seedream-5.0-pro | High-fidelity generation and edits |
| Seedream V5 Pro Unrestricted | seedream-5.0-pro | Supported Pro API route for this catalog entry |
| Nano Banana 2 Lite | nano-banana-2-lite | Cheapest Nano Banana for drafts and bulk runs |
| Nano Banana | nano-banana | The original Nano Banana (Gemini 2.5 Flash Image) |
| Krea 2 | krea-2-large or krea-2-medium | Text-to-image with up to 10 style references in `images`; one image per request |

~~~bash
curl -X POST "https://api.imageat.com/v1/images" \
  -H "Authorization: Bearer $IMAGEAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-pro",
    "prompt": "A cinematic product photograph on sculpted stone",
    "aspectRatio": "1:1",
    "resolution": "1K",
    "outputFormat": "png",
    "numImages": 1
  }'
~~~

Common fields: `model`, `prompt`, `images`, `aspectRatio`, `resolution`, `outputFormat`, and `numImages`. GPT Image 2 and GPT Image 2.5 also accept `quality`; GPT Image 2.5 and 2.6 add the `xhigh` and `max` tiers plus `transparentBackground`, which needs a `png` or `webp` `outputFormat`. GPT Image 2.5 turns `aspectRatio` and `resolution` into exact pixel dimensions, and falls back to a square when the ratio is not one it can render. Nano Banana 2.1 also accepts `21:9`, `5:4`, `4:5`, `4:1`, `1:4`, `8:1`, `1:8` and `auto` (keeps an edited image's framing), and `enableWebSearch: true` grounds the image in a live web search for $0.03 extra per request.

---

## Video models

All video models use `POST /v1/videos` and the same status endpoint.

| model | use | supported configuration |
|-------|-----|-------------------------|
| gemini-omni-12 | Text, image, first/last-frame (≤10s) or reference-image (up to 10) video, 16:9 or 9:16 | 3–15s · 360p/720p/1080p/4K · audio, from $0.055/sec |
| kling4 | Text, image, first/last-frame, reference-image (up to 10) or video edit (mode edit-video, billed per source second) | 3–30s · 720p/1080p, from $0.32/sec |
| flux3-max | Text, image, or first/last-frame video (firstFrameUrl + lastFrameUrl) | 5–20s · 720p/1080p · audio, from $1.71 |
| wan3 | Text, image, first/last-frame or reference-image video | 2–30s · 480p/720p/1080p · audio, from $0.20 |
| minimax-h3-max | Text, image, or first/last-frame video | 5–15s · 480p/768p, from $0.50 |
| seedance25 | Text, image, reference, or frame-controlled video | 4–30s · 480p/720p, from $0.83 |
| seedance25-flash | Faster, cheaper Seedance 2.5: text, image, reference, or first/last-frame video | 4–30s · 480p/720p, from $0.57 |
| midjourney-v8 | Image-to-video, 4 clips per run | 4 × 5s · 480p/720p, from $0.18 |
| pixverse | Text/image video with optional audio | 1–15s · up to 1080p, from $0.09/sec |
| veo | Default model. Text or image video | 4/6/8s · 720p/1080p/4K · audio, from $1.20 |
| veo-lite | Text, image, or first/last-frame video | 4/6/8s · 720p/1080p · audio, from $0.40 |
| sora | Text or image video | 4/8/12s · 720p/1080p, from $0.80 |
| kling | Text or image video | 5/10s · 720p/1080p · optional audio, from $0.70 |
| kling3 | Text or image video | 3–15s · 720p/1080p/4K · optional audio, from $0.34/sec |
| kling3-omni | Text or image video | 3–15s · 720p/1080p/4K · optional audio, from $0.42/sec |
| grok | Text or image video | 1–15s · 480p/720p, from $0.10/sec |
| grok-1-5 | Image-to-video | 1–15s · 480p/720p, from $0.17/sec |
| seedance2 | Text, image, or reference-image video | 4–15s · 480p/720p/1080p, from $1.08 |
| seedance2-mini | Text, image, or reference-image video | 5/10/15s · 480p/720p, from $0.36 |
| gemini-omni | Text or image video | 5/10s · 720p, from $2.12 |
| happyhorse | Text or image video | 5/10/15s · 720p/1080p, from $1.40 |
| happyhorse-ref | Reference-image video (referenceImageUrls) | 5/10/15s · 720p/1080p, from $1.40 |
| flux3 | Text or image video | 5–20s · 720p/1080p, from $1.70 |

Coming soon (not callable yet; requests return 503 until the provider API opens):



Omitting `model` selects `veo`. Switch the `model` field and its supported duration/resolution values; unsupported values return 422 with the valid list. Every asynchronous request returns `taskId` and `generationId`; poll `GET /v1/videos/status` until completed.

---

## Midjourney V8

`midjourney-v8` runs Midjourney V8.2 on both `POST /v1/images` and `POST /v1/videos`. No Midjourney subscription is needed. **Every run returns 4 outputs** and the price covers all four, so read `urls` rather than `url`.

- **Images:** $0.18 per run of 4 images ($0.26 at 2K HD). Text-to-image, or image-to-image when `images[0]` is set. Synchronous, about two minutes. `numImages` is ignored.
- **Video:** $0.18 per run of 4 × 5s clips at 480p ($0.52 at 720p). Image-to-video only.

| parameter | applies to | description |
|-----------|------------|-------------|
| prompt | image (required), video (optional) | Up to 1,024 characters |
| aspectRatio | image | 1:1, 9:16, 16:9, 4:3, 3:4, 2:3, 3:2, 9:21, or 21:9; other ratios snap to the nearest |
| resolution | image | 1K, or 2K for native 2K HD |
| images | image | Optional; images[0] is re-imagined, images[1] is a style reference |
| styleReferenceUrl | image | Optional style reference URL (same as images[1]) |
| stylize / chaos / weird | image | Optional, 0–1000 / 0–100 / 0–3000 |
| seed | image | Optional non-negative integer |
| imageUrl | video (required) | Public URL of the image to animate |
| resolution | video | 480p or 720p |
| motion | video | low or high |

~~~bash
curl -X POST "https://api.imageat.com/v1/images" \
  -H "Authorization: Bearer $IMAGEAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "midjourney-v8",
    "prompt": "A lighthouse on a basalt cliff at dusk, painterly, volumetric fog",
    "aspectRatio": "16:9",
    "resolution": "1K",
    "stylize": 250
  }'
~~~

The image response holds `url` (the first image), `urls` (all 4), `generationId` and `generationIds`.

~~~bash
curl -X POST "https://api.imageat.com/v1/videos" \
  -H "Authorization: Bearer $IMAGEAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "midjourney-v8",
    "imageUrl": "https://example.com/still.jpg",
    "prompt": "Slow push-in, fog drifting past the lighthouse",
    "resolution": "480p",
    "motion": "low"
  }'
~~~

The video request returns `taskId` and `generationId`. When `GET /v1/videos/status` reports `completed`, `urls` holds all four clips (`url` is the first). Webhook payloads carry `urls` too.

---

## Seedance 2.5 Video API

Generate videos from text, a first-frame image, or first and last frames.

- **Create:** POST /v1/videos
- **Status:** GET /v1/videos/status?taskId={taskId}&generationId={generationId}
- **Model:** seedance25
- **Duration:** 4–30 seconds
- **Resolution:** 480p or 720p

~~~bash
curl -X POST "https://api.imageat.com/v1/videos" \
  -H "Authorization: Bearer $IMAGEAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance25",
    "providerVariant": "more",
    "prompt": "A paper airplane glides through a softly lit studio",
    "duration": "5s",
    "resolution": "720p",
    "aspectRatio": "adaptive",
    "generateAudio": true,
    "outputFormat": "mp4",
    "watermark": false
  }'
~~~

The create response returns `status: pending`, a `taskId`, and a `generationId`. Poll the status endpoint every 5–10 seconds until it returns `status: completed` and a video `url`.

### Video parameters

| parameter | default | description |
|-----------|---------|-------------|
| model | required | Use `seedance25` |
| providerVariant | standard | Use `more` for this Seedance 2.5 endpoint |
| prompt | required | Scene, motion, camera, style, and audio direction |
| imageUrl | none | Optional first frame for image-to-video |
| firstFrameUrl / lastFrameUrl | none | Send both for a directed transition |
| duration | 5s | Whole seconds from 4s through 30s |
| resolution | 720p | `480p` or `720p` |
| aspectRatio | adaptive | `adaptive`, `16:9`, `9:16`, `4:3`, `3:4`, `1:1`, or `21:9` |
| generateAudio | true | Synchronized audio; no additional credit surcharge |
| outputFormat | mp4 | `mp4` or `mov` |
| watermark | false | Optional boolean watermark control |

~~~bash
curl "https://api.imageat.com/v1/videos/status?taskId=TASK_ID&generationId=GENERATION_ID" \
  -H "Authorization: Bearer $IMAGEAT_API_KEY"
~~~

~~~json
{
  "status": "completed",
  "url": "https://cdn.imageat.com/generated/video.mp4"
}
~~~

Model playground: https://imageat.com/models/seedance-2-5#playground

---

## Edit API

`POST /v1/edit` runs one edit feature on an existing image. Body: `{ feature, imageUrl, prompt?, maskUrl?, backgroundPrompt?, backgroundImageUrl?, options? }`. `GET /v1/edit/features` lists the features live. The response is `{ url, feature, creditsUsed, generationId }`.

| feature | name | API price |
|---------|------|-----------|
| remove-background | Remove Background | $0.04 |
| ideogram-remove-background | Ideogram Remove Background | $0.02 |
| object-eraser | Object Eraser | $0.10 |
| background-replace | Background Replace | $0.10 |
| ai-edit | AI Edit | $0.16 |
| ai-edit-pro | AI Edit Pro | From $0.40 |
| gpt-image-edit | GPT Image Edit | $0.50 |
| seedream-edit | Seedream Edit | $0.10 |
| inpaint-nano-banana-2 | Inpaint (Nano Banana 2) | $0.16 |
| inpaint-gpt | Inpaint (GPT Image) | $0.50 |
| inpaint-ideogram | Inpaint (Ideogram V3) | $0.40 |
| layerize | Layerize (Seedream 5.5) | From $0.15 |
| relight | Relight | $0.10 |
| perspective | Perspective Change | $0.10 |
| virtual-try-on | Virtual Try-On | $0.20 |
| virtual-try-on-google | Google Virtual Try-On | $0.15 |
| city-teleport | City Teleport | $0.08 |
| plastic-surgery | Plastic Surgery AI | $0.20 |
| post-processing | Post Processing | $0.01 |

`layerize` (Seedream 5.5) splits an image into a base image plus transparent PNG layers. `prompt` is optional (which elements to separate); `options.maxLayers` caps the returned images including the base (2 to 12, default 6) and `options.textRecognition: true` adds OCR text to text layers. The response adds `urls` (base image first, then the layers in stacking order) and `layers` (position and order of each layer). It is billed per returned image: about $0.07 each plus $0.03 for the input.

~~~bash
curl -X POST "https://api.imageat.com/v1/edit" \
  -H "Authorization: Bearer $IMAGEAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"feature":"ideogram-remove-background","imageUrl":"https://example.com/product.jpg"}'
~~~

---

## Audio API (text to speech)

`POST /v1/audio/speech` is synchronous. Body: `{ text, model, voice, stability?, timestamps? }`, up to 5,000 characters. List voices with `GET /v1/audio/voices`. The response is `{ status: "completed", url, durationSec, creditsUsed, generationId }`. With `timestamps: true`, ElevenLabs takes also return `words: [{ text, start, end }]` in seconds for caption timing; the field is absent when no word timings are available.

`POST /v1/audio/sound-effects` is synchronous too. Body: `{ text, durationSeconds?, loop? }`: `text` up to 450 characters, `durationSeconds` 0.5–22 (omit to let the model choose; billed as 22s), `loop: true` for seamless ambience. Returns `{ status: "completed", url, creditsUsed, generationId }` with an MP3 URL.

| model | name | price | use for |
|-------|------|-------|---------|
| elevenlabs-tts | Eleven v4 | $0.30 / 1K characters | Most natural narration; default model |
| gemini-tts | Gemini 2.5 TTS | $0.10 / 1K characters | Cheaper multilingual voices |

---

## Social API

Post images and videos to the Instagram, Facebook Page, LinkedIn and X accounts connected in Social Hub (https://imageat.com/social-hub). No credits; posting needs an imageat plan.

- `GET /v1/social/accounts` → `{ accounts: [{ id, platform, name, handle, status, can_publish, reason }], plan, connect_url }`
- `POST /v1/social/posts` → body `{ account_ids, caption?, captions?: { [account_id]: text }, generation_id? | media_url?, alt_text?, mode?: "draft" | "schedule" | "publish", scheduled_at?, timezone? }`. `mode` defaults to `draft`. `remind_account_ids` (a subset of `account_ids`) are reminded instead of posted to: the user gets an email at the scheduled time and posts it themselves. Media: https JPEG/PNG/WebP or MP4 up to 100 MB. Returns `201 { post: { id, status, scheduled_at, media, destinations: [{ account_id, platform, status, published_url, error }] } }`.
- `GET /v1/social/posts?status=&limit=`, `GET /v1/social/posts/{id}`, `DELETE /v1/social/posts/{id}` (cancel a draft or scheduled post).
- `GET /v1/social/autopilots`, `POST /v1/social/autopilots/{id}/queue` with `{ items: [{ caption?, generation_id? | media_url? }] }` (up to 30).
- Videos may stay `publishing` for a minute while the platform processes them. Limits: 60 posts per hour. `402` with `code: "plan_required"` means the plan does not cover posting or that account.

---

## FFmpeg API

Run real ffmpeg commands (FFmpeg 8: libx264, libx265, libvpx, SVT-AV1, MP3, Opus, subtitles/ass, loudnorm, palettegen) on up to 5 inputs. Jobs are asynchronous.

`POST /v1/ffmpeg/process` — body:

```json
{
  "inputs": [{ "url": "https://example.com/clip.mov" }],
  "outputs": [{ "name": "out.mp4", "options": ["-vf", "scale=-2:720", "-c:v", "libx264", "-crf", "23", "-c:a", "aac"] }],
  "timeout_seconds": 600,
  "webhook_url": "https://your.app/hooks/ffmpeg"
}
```

Or pass a command instead of `outputs`: `"command": "ffmpeg -i in0.mov -vn -c:a libmp3lame -b:a 192k out.mp3"`.

- Inputs are named `in0.<ext>`, `in1.<ext>`… from the URL path; set `"name": "in0.mp4"` when the URL has no extension. Per-input options go in `inputs[i].options`.
- Outputs must be named `out.<ext>` or `out-<name>.<ext>`, up to 5 per job.
- URL inputs must be public and up to 500 MB. For private or larger files (up to 2 GB), call `POST /v1/ffmpeg/uploads` with `{ "files": [{ "name": "in0.mp4", "bytes": 123456 }] }`, PUT each file to the returned `url` with `Content-Type: application/octet-stream`, then pass `{ "upload_id": "…" }` in place of `url`.
- URLs, absolute paths, `movie`/`amovie`, filter scripts and streaming muxers (HLS, DASH, tee) are rejected.

The response is `202` with the job. Poll `GET /v1/ffmpeg/jobs/{id}` (or use `webhook_url`, which receives `{ event: "ffmpeg.job.succeeded" | "ffmpeg.job.failed", job }`):

```json
{ "id": "ff_…", "object": "ffmpeg.job", "status": "succeeded", "outputs": [{ "name": "out.mp4", "bytes": 8123456, "url": "https://…" }], "run_seconds": 14.2, "price_usd": 0.03 }
```

Status is `queued`, `running`, `succeeded` or `failed` (with `error` and the ffmpeg `log` tail). Output URLs are valid for 24 hours and files are kept for 7 days.

**Pricing:** $0.01 per started minute of the job's run (download + ffmpeg + upload), $0.03 minimum, from the API balance. Creating a job holds the price of `timeout_seconds` + 2 minutes (default 600 s → $0.12) and returns the unused part when it ends. Failed jobs that end within a minute are free. At most 5 running jobs per account.

---

## Chat completions

Generate chat and reasoning responses through an OpenAI-compatible endpoint using the same Imageat API key. One endpoint serves every LLM in the catalog — switch models by changing the `model` field.

- **Endpoint:** POST /v1/chat/completions
- **Flagship uncensored model:** qwen/qwen3.8-27b-uncensored
- **Other Qwen 3.8 models:** qwen/qwen3-8-27b, qwen/qwen3-8-27b-obliterated, unsloth/qwen3-8-flash-next-gguf
- **GPT-6 Astra:** openai/gpt-6-astra — long-context reasoning, image input, web search, adjustable verbosity, and tool calls
- **Gemini 4 Argon:** google/gemini-4-argon — multimodal reasoning for long, multi-step coding, research, and document analysis; `reasoning` sets its thinking level (low, medium, high), with optional `web_search` or `google_maps` grounding
- **DeepSeek V4.1 Flash:** deepseek/v4-1-flash, deepseek/v4-1-flash-economy — 1M-context models with image input, optional thinking and native tool calls (Economy: same weights, 20% cheaper, slightly slower)
- **DeepSeek V4:** deepseek/v4-flash, deepseek/v4-pro — text-only 1M-context models with optional thinking and native tool calls
- **Other catalog models:** google/gemini-3.8-flash, google/gemini-3.7-flash, openai/gpt-5-6-sol, openai/gpt-5-6-terra, openai/gpt-5-6-luna, xai/grok-4-5, zhipu/glm-4.7-flash, openai/gpt-oss-20b, claude/sonnet-5, claude/opus-5 (call GET /v1/models for the current list)
- **Context window:** 262,144 tokens
- **Maximum output:** 4,000 tokens
- **Streaming:** supported (`"stream": true` returns text/event-stream)
- **Model discovery:** GET /v1/models

### Create a chat completion

~~~bash
curl -X POST "https://api.imageat.com/v1/chat/completions" \\
  -H "Authorization: Bearer $IMAGEAT_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "openai/gpt-6-astra",
    "messages": [
      {"role": "system", "content": "You are a concise product strategist."},
      {"role": "user", "content": "Suggest three retention features for Imageat."}
    ],
    "reasoning": "high",
    "verbosity": "medium",
    "web_search": true,
    "max_tokens": 500
  }'
~~~

Long or thinking-enabled requests can take several minutes. Keep the HTTP connection open until the final completion is returned.

### Gemini 4 Argon

Google's multimodal reasoning model for long, multi-step work. `reasoning` maps to Gemini's thinking level: `low`, `medium` (default) or `high` (`xhigh` and `max` are treated as `high`). Set `web_search` to ground the answer with Google Search, or `google_maps` to ground it with Google Maps place data. Use one at a time: when both are set, only web search is applied. `max_tokens` is not forwarded, because Gemini counts thinking tokens against its output limit; the model manages its own answer length. Image URL content parts are passed to the model as input files. Custom function tools are not supported by this provider.

~~~bash
curl -X POST "https://api.imageat.com/v1/chat/completions" \\
  -H "Authorization: Bearer $IMAGEAT_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "google/gemini-4-argon",
    "messages": [{"role": "user", "content": "Compare three coworking spaces near Karaköy for a 6-person team."}],
    "reasoning": "high",
    "google_maps": true
  }'
~~~

Billing is usage-based: 10 credits are reserved and the run settles to the provider cost, usually 1 credit for a short answer. The same model is available to MCP clients as the `imageat_ask_gemini_argon` tool.

Model playground: https://imageat.com/models/gemini-4-argon#playground

### DeepSeek V4 Flash and Pro

DeepSeek's text-only V4 models with a 1M-token context: `deepseek/v4-flash` (284B MoE, 13B active) for fast, low-cost chat and agent loops, and `deepseek/v4-pro` (1.6T MoE, 49B active) for the hardest coding and reasoning. Thinking is on by default and `reasoning` sets its effort (`low`, `medium`, `high`; `xhigh` and `max` are treated as `high`). Send `"enable_thinking": false` for the fastest answer; `max_tokens` only applies then, because the provider counts reasoning tokens against the limit. Only the final answer is returned in `message.content`. OpenAI-format `tools` come back as native `tool_calls`, including parallel calls. Image content parts are rejected with a 400 before any charge.

~~~bash
curl -X POST "https://api.imageat.com/v1/chat/completions" \\
  -H "Authorization: Bearer $IMAGEAT_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "deepseek/v4-flash",
    "messages": [{"role": "user", "content": "Refactor this function to remove the N+1 query."}],
    "reasoning": "high"
  }'
~~~

Billing is usage-based at 2× DeepSeek's token rates through the API: Flash $0.88 input and $2.64 output per 1M tokens, Pro $2.64 and $7.92 (reasoning counts as output). Website credits reserve 10 and settle to the measured cost, usually 1 credit for a short answer.

Model pages: https://imageat.com/models/deepseek-v4-flash and https://imageat.com/models/deepseek-v4-pro

### DeepSeek V4.1 Flash and V4.1 Flash Economy

`deepseek/v4-1-flash` (552B MoE, 8–16B active) takes the same parameters as V4 (`reasoning`, `enable_thinking`, `tools`) and also reads images: send up to 10 OpenAI-format `image_url` content parts (JPEG, PNG, or WebP). `deepseek/v4-1-flash-economy` serves the same weights for 20% less per token with slightly slower generation, for batch and background work.

Billing is usage-based at 2× DeepSeek's measured token cost: during DeepSeek's peak hours (Mon–Fri 09:00–12:00 and 14:00–18:00 Beijing time) V4.1 Flash is $0.60 input and $2.40 output per 1M tokens and Economy $0.48 and $1.92; off-peak it is half. Reasoning counts as output.

Model pages: https://imageat.com/models/deepseek-v4-1-flash and https://imageat.com/models/deepseek-v4-1-flash-economy

### OpenAI-compatible clients

Any tool that speaks the OpenAI API (opencode, Cline, Continue, the OpenAI SDKs, the Vercel AI SDK) works by pointing its base URL at `https://api.imageat.com/v1` — including the `/v1`, since `https://api.imageat.com` alone returns 404 — and using the Imageat key as the API key.

~~~bash
export OPENAI_BASE_URL="https://api.imageat.com/v1"
export OPENAI_API_KEY="$IMAGEAT_API_KEY"
~~~

`GET https://api.imageat.com/v1/models` lists every model ID this endpoint accepts.

Streaming requests answer with `text/event-stream` and OpenAI-style `chat.completion.chunk` events terminated by `data: [DONE]`. The provider runs as a batch task, so the response is buffered until the model finishes and then streamed out; the connection is held open with SSE comment pings in the meantime.

Agent clients may send OpenAI-format `tools` and `tool_choice`. Function selections return structured `message.tool_calls` (or streamed `delta.tool_calls`) with `finish_reason: "tool_calls"`. Send the function result back as a `role: "tool"` message with the matching `tool_call_id` to continue the agent loop.

The newer Responses API is also available at `POST https://api.imageat.com/v1/responses`. It accepts `instructions`, string or item-array `input`, function tools, `tool_choice`, and `stream`. Streaming uses typed events such as `response.output_text.delta`, `response.function_call_arguments.done`, and `response.completed`. Continue a function loop by including the prior `function_call` and matching `function_call_output` items in the next request's `input`.

~~~bash
curl -X POST "https://api.imageat.com/v1/responses" \\
  -H "Authorization: Bearer $IMAGEAT_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{"model":"qwen/qwen3.8-27b-uncensored","input":"Give me a two-line launch checklist","stream":true}'
~~~

Stored Responses support `previous_response_id`, `GET /v1/responses/{response_id}`, `DELETE /v1/responses/{response_id}`, and `POST /v1/responses/{response_id}/cancel`. Set `store: false` for stateless requests.

### Reliability and asynchronous jobs

- Send `Idempotency-Key` on non-streaming image, video, chat, and Responses requests. The response is retained for 24 hours and replayed without charging twice.
- Every v1 response includes `x-request-id`; optionally send `x-client-request-id` for your own correlation ID.
- Rate-limit responses include `Retry-After`.
- Video creation accepts `webhook_url` for completion/failure delivery and an optional 16–256 character `webhook_secret` for HMAC-SHA256 `x-imageat-signature` verification.
- Cancel an unfinished video with `POST /v1/videos/cancel` and both `taskId` and `generationId`.
- Discover media models through `GET /v1/models/images` and `GET /v1/models/videos`.
- OpenAPI 3.1 schema: https://api.imageat.com/openapi.yaml

### OpenCode configuration

~~~json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "imageat": {
      "npm": "@ai-sdk/openai-compatible",
      "options": { "baseURL": "https://api.imageat.com/v1", "apiKey": "{env:IMAGEAT_API_KEY}" },
      "models": { "qwen/qwen3.8-27b-uncensored": { "name": "Qwen 3.8" } }
    }
  },
  "model": "imageat/qwen/qwen3.8-27b-uncensored"
}
~~~

`{env:IMAGEAT_API_KEY}` is read from the environment OpenCode starts in. If it is unset, OpenCode sends no key and every request fails with `Unauthorized: Missing API key`. Set it before launching OpenCode (`export IMAGEAT_API_KEY=iat_live_…` on macOS/Linux, `setx IMAGEAT_API_KEY iat_live_…` on Windows, then open a new terminal), or paste the key directly into `apiKey`.

### Request parameters

| parameter | default | description |
|-----------|---------|-------------|
| model | Qwen model ID | Any ID returned by GET /v1/models |
| stream | false | true returns OpenAI-style server-sent events |
| tools | — | OpenAI-format function definitions available to the model |
| tool_choice | auto | auto, none, required, or a specific function |
| messages | required | System, user, and assistant messages |
| enable_thinking | true | Deeper reasoning or shorter direct answers |
| temperature | 0.7 | Output randomness |
| top_p / top_k | 0.95 / 20 | Probability sampling controls |
| max_tokens | 1000 | Maximum output tokens; capped at 4,000 |
| min_tokens | 0 | Minimum output-token target |
| repetition_penalty | 1.0 | Reduces repeated phrases and loops |
| length_penalty | 1.0 | Biases toward shorter or longer output |
| stop | none | String or array of stop sequences |
| seed | 123456 | Optional repeatability seed |
| quantization / do_sample | true / true | Efficiency and sampling toggles |
| user / session_id | none | Optional conversation identifiers |

### Response

~~~json
{
  "id": "chatcmpl_2747897",
  "object": "chat.completion",
  "model": "qwen/qwen3.8-27b-uncensored",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "..." },
    "finish_reason": "stop"
  }],
  "credits_used": 2,
  "billing": {
    "reserved_credits": 3,
    "provider_cost_usd": 0.0324,
    "elapsed_seconds": 54
  }
}
~~~

Read generated text from **choices[0].message.content**.

API-key requests reserve up to **$0.30 for Qwen 3.8 27B Uncensored** or **$1.00 for the other catalog LLMs**, settle to the measured execution usage, and return the final charge in `billing.amount_usd`. Unused balance is returned automatically, and failed requests receive a full refund. Website-session requests continue to report equivalent credit fields.

`model`, `messages`, `max_tokens`, and `stream` apply to every model. The sampling controls (`enable_thinking`, `temperature`, `top_p`, `top_k`, the penalties, `stop`, `seed`, `quantization`, `do_sample`) are available on the Qwen 3.8 family; other models ignore them.

LLM errors: **400** for invalid messages or an unsupported model, **402** for insufficient API balance, **429** for rate limits, and **502** when the model request fails.

Qwen playgrounds:
- https://imageat.com/models/qwen-3-8-27b-uncensored#playground
- https://imageat.com/models/qwen-3-8-27b#playground
- https://imageat.com/models/qwen-3-8-27b-obliterated#playground
- https://imageat.com/models/qwen-3-8-flash-next-gguf#playground

---

## Run lifecycle

A run moves through these states:

- `queued` — accepted, waiting for a worker
- `running` — worker executing nodes
- `completed` — all outputs ready
- `failed` — one or more nodes failed; check `error`
- `cancelled` — cancelled before completion

Credits are reserved at run creation and settled (refund of unused portion) once the run completes or fails. The final response includes `credits_used`.

---

## Create a run

`POST /v1/workflows/{workflow_id}/runs` — start a run of a published workflow.

**Request:**
```
POST https://api.imageat.com/v1/workflows/wf_abc123/runs
Authorization: Bearer iat_live_...
Content-Type: application/json
Idempotency-Key: 8f3b... (optional)

{
  "nodes": [],
  "edges": [],
  "webhook": {
    "url": "https://your-app.com/webhook/imageat",
    "secret": "whsec_..."
  }
}
```

If you pass empty `nodes`/`edges`, the saved (published) workflow graph is used. Pass them to override inputs (e.g. a different prompt) per-run.

**Response · 202:**
```json
{
  "run_id": "run_01HX...",
  "status": "queued"
}
```

Idempotency: send the same `Idempotency-Key` to safely retry a request — the same run is returned instead of creating a duplicate.

---

## Poll a run

`GET /v1/runs/{run_id}`

**Response · 200:**
```json
{
  "run_id": "run_01HX...",
  "status": "completed",
  "outputs": {
    "node_output_1": {
      "type": "image",
      "value": "https://cdn.imageat.com/runs/run_01HX.../node_output_1.png"
    }
  },
  "credits_used": 12,
  "created_at": "2026-05-22T10:01:24Z",
  "completed_at": "2026-05-22T10:01:38Z"
}
```

Poll every 1–2 seconds while the status is `queued` or `running`. For faster feedback, use SSE.

---

## List runs for a workflow

`GET /v1/workflows/{workflow_id}/runs` — paginated history of runs you own, newest first.

**Query parameters (all optional):**

| param      | type   | notes |
|------------|--------|-------|
| `status`   | string | `queued`, `running`, `completed`, `failed`, `cancelled` |
| `since`    | ISO 8601 | filter `created_at >= since` |
| `until`    | ISO 8601 | filter `created_at <= until` |
| `limit`    | int (1–100) | default `20` |
| `cursor`   | string | opaque cursor returned by previous response |

**Response · 200:**
```json
{
  "runs": [
    {
      "run_id": "run_01HX...",
      "status": "completed",
      "credits_used": 12,
      "created_at": "2026-05-22T10:01:24Z",
      "completed_at": "2026-05-22T10:01:38Z"
    }
  ],
  "next_cursor": "eyJ0IjoiMjAyNi0w..."
}
```

`next_cursor` is `null` when there are no more pages. Pagination is cursor-based (keyset) so newly-created runs never cause duplicates or skipped rows between pages. Pass the cursor verbatim as `?cursor=...` to fetch the next page. List responses are slim by design — fetch `GET /v1/runs/{run_id}` for full outputs.

---

## Server-sent events (live updates)

`GET /v1/runs/{run_id}/events`

Returns a `text/event-stream`. Each event is a JSON line emitted as nodes start, finish, or the run terminates. The stream closes after `run_complete` or `run_failed`.

```
data: {"event":"node_start","node_id":"n1"}

data: {"event":"node_complete","node_id":"n1","output":{...}}

data: {"event":"run_complete","run_id":"run_01HX..."}
```

---

## Cancel a run

`POST /v1/runs/{run_id}/cancel`

Cancels a `queued` or `running` run. Reserved credits are refunded; already-executed node costs are kept.

**Response · 200:** `{ "ok": true }`

---

## Outputs & CDN URLs

Final outputs are mirrored to `cdn.imageat.com` so URLs are stable and fast. The path format is:

```
https://cdn.imageat.com/runs/{run_id}/{node_id}.{ext}
```

Each output entry has a `type` describing how to consume the value:

| type | value |
|------|-------|
| `image` | Single CDN image URL |
| `images` | Array of image URLs |
| `video` | CDN video URL (mp4) |
| `text` | Plain text (e.g. LLM output) |

---

## Rate limits & concurrency

Each API key is rate limited per minute, and each account has a cap on concurrent runs. Limits follow the owning account's active subscription plan.

| Plan | Requests / min | Concurrent runs |
|------|----------------|-----------------|
| Pro | 60 | 5 |
| Mega | 300 | 20 |
| Ultra | 600 | 50 |
| Business | 1,200 | 100 |

Every response includes:

```
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1716372960
X-RateLimit-Plan: Mega
```

`X-RateLimit-Reset` is the unix epoch second at which the current window resets.

When the per-minute quota is exhausted, requests return `429` with a `Retry-After` header (seconds):

```json
{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded for plan \"Mega\" (300 requests/minute). Retry in 23s.",
  "retry_after": 23
}
```

When the concurrent-run cap is reached, `POST /v1/workflows/{id}/runs` returns `429` with no `Retry-After` — retry once an in-flight run reaches `completed`, `failed`, or `cancelled`:

```json
{
  "error": "concurrency_limit_exceeded",
  "message": "Concurrent run limit reached for plan \"Mega\" (20).",
  "active_runs": 20,
  "limit": 20
}
```

Need higher limits? Email **info@imageat.com** with your account email and expected throughput.

---

## Webhooks

Pass a `webhook` object on run creation to receive a signed POST when the run terminates — no polling required. The same payload is sent for both `run_complete` and `run_failed` events.

```
POST https://your-app.com/webhook/imageat
X-Imageat-Signature: t=1716372924,v1=sha256(...)
X-Imageat-Event: run_complete
X-Imageat-Delivery: 7f1b...
Content-Type: application/json

{
  "event": "run_complete",
  "run_id": "run_01HX...",
  "status": "completed",
  "outputs": { ... },
  "credits_used": 12,
  "created_at": "2026-05-22T10:01:24Z",
  "completed_at": "2026-05-22T10:01:38Z"
}
```

**Retry policy.** Endpoints must respond with a 2xx within 10 seconds. Non-2xx responses, timeouts, and network errors are retried up to 5 total attempts with exponential backoff (30s, 2m, 10m, 1h). Use `X-Imageat-Delivery` to dedupe — the same id is sent on every retry.

**Signature verification.** Compute HMAC-SHA256 over `{timestamp}.{raw_body}` using your webhook `secret` and compare in constant time. Reject signatures whose timestamp is more than 5 minutes old to prevent replay.

```typescript
import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(secret: string, header: string, rawBody: string) {
  const m = /t=(\d+),v1=([a-f0-9]+)/.exec(header);
  if (!m) return false;
  const ts = Number(m[1]);
  if (Math.abs(Date.now() / 1000 - ts) > 300) return false;
  const expected = createHmac("sha256", secret)
    .update(\`\${ts}.\${rawBody}\`)
    .digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(m[2], "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}
```

---

## Error codes

| status | meaning |
|--------|---------|
| `401` | Missing or invalid API key |
| `402` | Insufficient credits — response includes `balance` and `required` |
| `403` | Run belongs to a different account |
| `404` | Workflow or run not found, or workflow not published |
| `422` | Invalid request body (bad nodes/edges) |
| `429` | Rate limit or concurrent-run cap exceeded — see [Rate limits](#rate-limits-concurrency) |
| `500` | Internal worker error — safe to retry with the same Idempotency-Key |

---

## Code examples

### cURL

```bash
# 1. Create a run
RUN=$(curl -s -X POST https://api.imageat.com/v1/workflows/wf_abc123/runs \
  -H "Authorization: Bearer $IMAGEAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"nodes": [], "edges": []}' | jq -r .run_id)

# 2. Poll until complete
while true; do
  RES=$(curl -s https://api.imageat.com/v1/runs/$RUN \
    -H "Authorization: Bearer $IMAGEAT_API_KEY")
  STATUS=$(echo "$RES" | jq -r .status)
  [ "$STATUS" = "completed" ] && echo "$RES" | jq .outputs && break
  [ "$STATUS" = "failed" ] && echo "$RES" | jq . && exit 1
  sleep 2
done
```

### Node.js

```typescript
const API_KEY = process.env.IMAGEAT_API_KEY!;
const BASE = "https://api.imageat.com/v1";

async function runWorkflow(workflowId: string) {
  const create = await fetch(\`\${BASE}/workflows/\${workflowId}/runs\`, {
    method: "POST",
    headers: {
      Authorization: \`Bearer \${API_KEY}\`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ nodes: [], edges: [] }),
  });
  if (!create.ok) throw new Error(\`create failed: \${create.status}\`);
  const { run_id } = await create.json();

  while (true) {
    await new Promise((r) => setTimeout(r, 1500));
    const poll = await fetch(\`\${BASE}/runs/\${run_id}\`, {
      headers: { Authorization: \`Bearer \${API_KEY}\` },
    });
    const data = await poll.json();
    if (data.status === "completed") return data;
    if (data.status === "failed") throw new Error(data.error);
  }
}

const result = await runWorkflow("wf_abc123");
console.log(result.outputs, result.credits_used);
```

### Python

```python
import os, time, requests

API_KEY = os.environ["IMAGEAT_API_KEY"]
BASE = "https://api.imageat.com/v1"
H = {"Authorization": f"Bearer {API_KEY}"}

def run_workflow(workflow_id: str) -> dict:
    r = requests.post(
        f"{BASE}/workflows/{workflow_id}/runs",
        headers={**H, "Content-Type": "application/json"},
        json={"nodes": [], "edges": []},
    )
    r.raise_for_status()
    run_id = r.json()["run_id"]

    while True:
        time.sleep(1.5)
        data = requests.get(f"{BASE}/runs/{run_id}", headers=H).json()
        if data["status"] == "completed":
            return data
        if data["status"] == "failed":
            raise RuntimeError(data.get("error", "run failed"))

result = run_workflow("wf_abc123")
print(result["outputs"], result["credits_used"])
```
