# AIGate API Agent Guide

Use this file as compact context for coding agents that need to integrate with AIGate without reading the full documentation site.

## Essentials

- Base URL: `https://api.aigate.shop/v1`
- Authentication: `Authorization: Bearer sk-your-api-key`
- Content type for JSON requests: `Content-Type: application/json`
- Model ids must be exact catalog ids, usually in `provider/model-id` format.
- `GET /v1/models` is the source of truth for currently visible models.
- Keep API keys on the server. Do not put keys in browser code, mobile apps, logs, screenshots, or public repositories.

## Endpoint Selection

| Task | Endpoint | Notes |
| --- | --- | --- |
| List models | `GET /v1/models` | API key is optional; a key can filter by account limits. |
| Account balance | `GET /v1/balance` | Requires an API key. |
| Chat/text generation | `POST /v1/chat/completions` | OpenAI-compatible chat route. |
| Responses API | `POST /v1/responses` | Use for OpenAI Responses-style clients. |
| Anthropic Messages | `POST /v1/messages` | Use for Anthropic Messages-style clients. |
| Embeddings | `POST /v1/embeddings` | Use embedding model ids from `/v1/models`. |
| GPT Image generation | `POST /v1/images/generations` | Use `openai/gpt-image-2` or exact GPT Image catalog id. |
| GPT Image editing | `POST /v1/images/edits` | Send source images in `images`. |
| Gemini image generation/editing | `POST /v1/chat/completions` | Use Gemini image model ids such as `google/gemini-3.1-flash-image-preview` or `google/gemini-3-pro-image` with `modalities: ["image", "text"]`. |
| Video generation | `POST /v1/video/generations` | Synchronous long-running request; use a 10-15 minute client timeout. |
| OpenAI-style video compatibility | `POST /v1/videos` | Accepted for compatible clients; prefer `/v1/video/generations` for new integrations. |

## OpenAI SDK Setup

```ts
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.AIGATE_API_KEY,
  baseURL: "https://api.aigate.shop/v1",
});
```

## Chat Example

```ts
const response = await client.chat.completions.create({
  model: "openai/gpt-5.5",
  messages: [
    { role: "system", content: "You are concise." },
    { role: "user", content: "Explain AIGate in one sentence." },
  ],
  temperature: 0.4,
  max_tokens: 120,
});

console.log(response.choices[0]?.message?.content);
```

## Streaming Chat Example

```ts
const stream = await client.chat.completions.create({
  model: "openai/gpt-5.5",
  messages: [{ role: "user", content: "Count to three." }],
  stream: true,
  stream_options: { include_usage: true },
});

for await (const chunk of stream) {
  const text = chunk.choices[0]?.delta?.content;
  if (text) process.stdout.write(text);
}
```

## Coding Agents and IDEs

Use AIGate as a custom provider in coding tools that support OpenAI-compatible or Anthropic-compatible APIs.

General values:

- OpenAI-compatible base URL: `https://api.aigate.shop/v1`
- Anthropic-compatible base URL: `https://api.aigate.shop/v1`
- API key: `sk-your-api-key`
- Model id: exact id from `GET /v1/models`, for example `openai/gpt-5.5` or `anthropic/claude-sonnet-4.6`

### Kilo Code

In Kilo Code settings, choose `OpenAI Compatible`.

```txt
Provider: OpenAI Compatible
Base URL: https://api.aigate.shop/v1
API key: sk-your-api-key
Model ID: openai/gpt-5.5
```

If Kilo asks for a full endpoint URL instead of a base URL, use `https://api.aigate.shop/v1/chat/completions`.

### OpenCode

Run `/connect`, choose `Other`, enter provider id `aigate`, and paste the AIGate API key. Then add this to `opencode.json` in the project root:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "aigate": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "AIGate",
      "options": {
        "baseURL": "https://api.aigate.shop/v1",
        "apiKey": "{env:AIGATE_API_KEY}"
      },
      "models": {
        "openai/gpt-5.5": {
          "name": "GPT 5.5"
        },
        "anthropic/claude-sonnet-4.6": {
          "name": "Claude Sonnet 4.6"
        }
      }
    }
  }
}
```

Set `AIGATE_API_KEY` in the shell that starts OpenCode, then run `/models` and select the AIGate model.

### Claude Code

Claude Code uses the Anthropic Messages route. AIGate supports `/v1/messages` with `x-api-key` and bearer authentication.

macOS / Linux:

```bash
export ANTHROPIC_BASE_URL=https://api.aigate.shop/v1
export ANTHROPIC_API_KEY=sk-your-api-key
export ANTHROPIC_MODEL=anthropic/claude-sonnet-4.6
export ANTHROPIC_DEFAULT_SONNET_MODEL=anthropic/claude-sonnet-4.6
export ANTHROPIC_DEFAULT_OPUS_MODEL=anthropic/claude-opus-4.7
export ANTHROPIC_DEFAULT_HAIKU_MODEL=anthropic/claude-haiku-4.5

claude
```

Windows PowerShell:

```powershell
$env:ANTHROPIC_BASE_URL="https://api.aigate.shop/v1"
$env:ANTHROPIC_API_KEY="sk-your-api-key"
$env:ANTHROPIC_MODEL="anthropic/claude-sonnet-4.6"
$env:ANTHROPIC_DEFAULT_SONNET_MODEL="anthropic/claude-sonnet-4.6"
$env:ANTHROPIC_DEFAULT_OPUS_MODEL="anthropic/claude-opus-4.7"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL="anthropic/claude-haiku-4.5"

claude
```

### Codex

Add a custom provider to `~/.codex/config.toml` on macOS/Linux or `%USERPROFILE%\.codex\config.toml` on Windows:

```toml
model_provider = "aigate"
model = "openai/gpt-5.5"

[model_providers.aigate]
name = "AIGate"
base_url = "https://api.aigate.shop/v1"
env_key = "AIGATE_API_KEY"
wire_api = "responses"
```

Set the key before starting Codex:

```bash
# macOS / Linux
export AIGATE_API_KEY=sk-your-api-key

# Windows PowerShell
$env:AIGATE_API_KEY="sk-your-api-key"
```

For other tools, use OpenAI-compatible mode when the client calls `/v1/chat/completions` or `/v1/responses`, and Anthropic-compatible mode when the client calls `/v1/messages`.

## GPT Image Generation

Use GPT Image models on the image endpoint, not the chat endpoint.

```bash
curl https://api.aigate.shop/v1/images/generations \
  -H "Authorization: Bearer $AIGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-2",
    "prompt": "A clean studio product photo of a matte black smart speaker on glass, softbox lighting",
    "quality": "medium",
    "size": "1024x1024",
    "n": 1
  }'
```

Read the result from `data[0].b64_json` or `data[0].url`.

```ts
import { writeFileSync } from "node:fs";

const image = response.data[0];

if (image.b64_json) {
  writeFileSync("gpt-image.png", Buffer.from(image.b64_json, "base64"));
} else if (image.url) {
  console.log(image.url);
}
```

## GPT Image Editing

```bash
curl https://api.aigate.shop/v1/images/edits \
  -H "Authorization: Bearer $AIGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-2",
    "prompt": "Add a small orange cat sitting on the table. Keep the original lighting and style.",
    "images": [
      { "image_url": "https://example.com/source.png" }
    ]
  }'
```

## Gemini Image Generation

Gemini image models work through chat completions. Do not send them to `/v1/images/generations` or `/v1/images/edits`.

```bash
curl https://api.aigate.shop/v1/chat/completions \
  -H "Authorization: Bearer $AIGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-3.1-flash-image-preview",
    "messages": [
      {
        "role": "user",
        "content": "Generate an image of a small yellow banana-shaped robot on a white desk, studio lighting"
      }
    ],
    "modalities": ["image", "text"]
  }'
```

To request aspect ratio or output size, pass `image_config` at the top level:

```json
{
  "model": "google/gemini-3-pro-image",
  "messages": [
    {
      "role": "user",
      "content": "Generate a sharp futuristic product render of a matte black AI gateway device on a white desk, studio lighting"
    }
  ],
  "modalities": ["image", "text"],
  "image_config": {
    "aspect_ratio": "16:9",
    "image_size": "2K"
  }
}
```

Read the image from `choices[0].message.images[0].image_url.url`. The URL can be a `data:image/...;base64,...` data URL.

### SillyImages / Gemini-Compatible Route

SillyImages for SillyTavern uses the Google Gemini-compatible route instead of OpenAI chat completions.

Use these settings:

```text
API type: Gemini (nano-banana)
Endpoint URL: https://api.aigate.shop
API key: $AIGATE_API_KEY
Model: google/gemini-3-pro-image
```

The extension will send generation requests to:

```text
POST https://api.aigate.shop/v1beta/models/{model}:generateContent
```

That route accepts Google-style `contents` and `generationConfig.imageConfig`, then returns the image in `candidates[0].content.parts[].inlineData`.

## Video Generation

Video generation is synchronous: the HTTP request stays open while the provider renders the video. Use a generous timeout.

```bash
curl --max-time 900 https://api.aigate.shop/v1/video/generations \
  -H "Authorization: Bearer $AIGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "provider/video-model-id",
    "prompt": "A cinematic shot of a glass sphere floating over a neon city",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "audio": false,
    "n": 1
  }'
```

Image-to-video can use `prompt: { "text": "...", "image": "https://..." }` or a string `prompt` with `input_image`, `input_image_url`, `image_url`, `image`, or `input_image_b64`.

Video-to-video can use `input_video` or `input_video_b64` when the selected model supports it.

Supported video parameters:

| Field | Required | Notes |
| --- | --- | --- |
| `model` | yes | Exact video model id from `/v1/models`. |
| `prompt` | yes | String prompt, or `{ "text": "...", "image": "..." }` for image-to-video. |
| `input_image`, `image`, `image_url`, `input_image_url` | no | Source image URL, data URL, or another value supported by the model. |
| `input_image_b64` | no | Explicit base64 image input. |
| `input_video`, `input_video_b64` | no | Source video for models that support video input. |
| `duration` | no | Clip length in seconds, if supported by the model. |
| `resolution` | no | Examples: `480p`, `720p`, `1080p`, `4K`, or `WIDTHxHEIGHT`. |
| `aspect_ratio` | no | Examples: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`. |
| `n` | no | Number of output videos. Defaults to `1` when omitted. |
| `audio` | no | Enable or disable audio when supported. |
| `quality` | no | Examples: `draft`, `std`, `pro`, when supported. |
| `negative_prompt` | no | Content to avoid. |
| `seed` | no | Deterministic generation seed when supported. |
| `user` | no | Optional client-side user identifier. |
| `provider_options` | no | Provider-specific options, for example Kling `cfg_scale` or `camera_control`. |

Kling models use the same endpoint. Keep shared settings at the top level and put Kling-specific values in `provider_options`:

```bash
curl --max-time 900 https://api.aigate.shop/v1/video/generations \
  -H "Authorization: Bearer $AIGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "klingai/kling-v3.0-t2v",
    "prompt": "A realistic cinematic product shot, slow dolly camera movement, natural light",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "audio": false,
    "quality": "std",
    "negative_prompt": "text, watermark, blurry, distorted hands",
    "seed": 42,
    "n": 1,
    "provider_options": {
      "cfg_scale": 0.65
    }
  }'
```

The response includes temporary file links:

```json
{
  "created": 1780047578,
  "model": "provider/video-model-id",
  "duration": 5,
  "videos": [
    {
      "url": "https://api.aigate.shop/v1/videos/task_id/content",
      "mime_type": "video/mp4"
    }
  ]
}
```

Download `videos[0].url` soon. AIGate video content links are temporary and can expire.

## Embeddings

```bash
curl https://api.aigate.shop/v1/embeddings \
  -H "Authorization: Bearer $AIGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "provider/embedding-model-id",
    "input": "Text to embed"
  }'
```

Use an embedding model id returned by `/v1/models`.

## Balance

```bash
curl https://api.aigate.shop/v1/balance \
  -H "Authorization: Bearer $AIGATE_API_KEY"
```

Typical fields:

- `balance`: current account balance in USD.
- `used`: accumulated account spend in USD.
- `token.remaining`: remaining balance assigned to this API key.
- `token.used`: spend made through this API key.
- `token.unlimited_quota`: if `true`, the key spends from account balance instead of its own fixed quota.

To measure one request cost through API only, call `/v1/balance` before and after the request and subtract `token.used`.

## Error Handling

Errors use an OpenAI-compatible shape:

```json
{
  "error": {
    "message": "Human readable message",
    "type": "api_error",
    "param": null,
    "code": "model_not_found",
    "status": 503
  }
}
```

Common statuses:

| Status | Meaning | Agent action |
| --- | --- | --- |
| 400 | Bad JSON, wrong endpoint, unsupported parameter, invalid image/video option, or provider safety rejection. | Check body and remove optional fields. |
| 401 | Missing or invalid API key. | Check `Authorization: Bearer ...`. |
| 402 | Not enough balance or quota. | Ask the user to top up or reduce request cost. |
| 403 | No access to the model or account verification required. | Check exact model id and account status. |
| 404 | Wrong route, missing resource, or unknown model id. | Verify endpoint and exact id. |
| 410 | Temporary generated content link expired. | Generate again or download sooner. |
| 413 | Input or context is too large. | Reduce messages/input or choose a larger-context model. |
| 429 | Rate limit, token limit, concurrency limit, or quota-style limit. | Retry with backoff and reduce parallelism. |
| 500 | Internal or unexpected provider response. | Retry later. |
| 502 | Provider temporarily unavailable or overloaded. | Retry with backoff or choose another model. |
| 503 | Model temporarily unavailable or no working route. | Check model id, retry later, or choose another model. |

## Agent Checklist

1. Read the user's desired task: text, image, video, embeddings, or balance.
2. Call `GET /v1/models` if the exact model id is unknown.
3. Pick the endpoint from the endpoint table. Do not guess image/video endpoints from the model name alone.
4. Keep the API key in an environment variable such as `AIGATE_API_KEY`.
5. Start with the smallest valid request, then add optional parameters.
6. Use retries with exponential backoff for 429, 500, 502, and 503.
7. Do not retry blindly on 400, 401, 402, 403, 404, or 413; fix the request or ask the user.
8. For images, inspect the documented response location instead of assuming `message.content` contains the image.
9. For video, set a long timeout and save temporary links quickly.
10. Never expose keys, internal logs, balances, provider details, or private prompts unless the user explicitly asks and it is safe.