AGNES/GATEWAY
GitHub

OPENAI-COMPATIBLE GATEWAY

One OpenAI shape.
Every Agnes modality.

Use existing OpenAI clients for Agnes chat, image, image-editing, and video generation—without a server-side API key or hidden model mapping.

Test it nowView on GitHub
  • Open source
  • Self-hosted
  • Keys never persisted
gateway.request
curl https://agnes-compatible-gateway.zo.deno.net/v1/chat/completions \
  -H "Authorization: Bearer $AGNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-2.0-flash",
    "messages": [{"role":"user","content":"Hello, Agnes."}],
    "stream": true
  }'
OpenAI-compatible/v1/chat/completions

USE YOUR OWN KEY

Run a real request

Your Agnes key stays only in this page's memory.

Never saved to cookies, localStorage, or analytics.

RequestPOST /v1/chat/completions
ResultREADY
</>

Your response will appear here.

EXPLICIT, NOT MAGICAL

Know exactly what changes

The gateway transforms only the mismatches it can resolve safely.

Capability / routeOpenAI inputGateway behaviorSupport
Chat/v1/chat/completionsmodel, messages, streamModel passes through; developer becomes system; max_completion_tokens becomes max_tokens.Transformed
Image generation/v1/images/generationsprompt, model, size, nDefaults size to 1024x1024; response_format is converted; n fans out atomically.Transformed
Image edits/v1/images/editsmultipart image / image[]Files become Data URIs in Agnes extra_body.image.Transformed
Video creation/v1/videosprompt, seconds, sizeseconds becomes 24 fps frame count; size is split into width and height.Transformed
Video retrieval/v1/videos/{id}GET /v1/videos/{id}The public ID is the stateless Agnes task ID.Pass-through
Video content/v1/videos/{id}/contentGET /v1/videos/{id}/contentCompleted media is streamed; thumbnail and spritesheet variants fall back to video.Partial
Chat/v1/chat/completions
Transformed
OpenAI input
model, messages, stream
Gateway behavior
Model passes through; developer becomes system; max_completion_tokens becomes max_tokens.
Image generation/v1/images/generations
Transformed
OpenAI input
prompt, model, size, n
Gateway behavior
Defaults size to 1024x1024; response_format is converted; n fans out atomically.
Image edits/v1/images/edits
Transformed
OpenAI input
multipart image / image[]
Gateway behavior
Files become Data URIs in Agnes extra_body.image.
Video creation/v1/videos
Transformed
OpenAI input
prompt, seconds, size
Gateway behavior
seconds becomes 24 fps frame count; size is split into width and height.
Video retrieval/v1/videos/{id}
Pass-through
OpenAI input
GET /v1/videos/{id}
Gateway behavior
The public ID is the stateless Agnes task ID.
Video content/v1/videos/{id}/content
Partial
OpenAI input
GET /v1/videos/{id}/content
Gateway behavior
Completed media is streamed; thumbnail and spritesheet variants fall back to video.

DEPLOY YOUR WAY

Deploy

Run the published image with one optional upstream URL. No database or secrets service is required.

Optional environment variableAGNES_BASE_URL=https://apihub.agnes-ai.com/v1
Read deployment guide
01

Docker

Run the published image with one optional upstream URL. No database or secrets service is required.

docker run --rm -p 8000:8000 \ -e AGNES_BASE_URL=https://apihub.agnes-ai.com/v1 \ ghcr.io/4x25/agnes-compatible-gateway:latest
02

Deno Deploy

Fork the repository, connect it to Deno Deploy, and use the Fresh preset. The default Agnes endpoint works without configuration.

console.deno.com

DIAGNOSE FROM THE EDGE

Common failures are kept visible

01401 / 403

Check the Agnes key and whether it can use the requested model. The gateway never substitutes another credential.

02404

Verify the gateway base URL and compatible route. Video APIs use /v1/videos, not /v1/video/generations.

03429

The response comes from Agnes account limits. Inspect Retry-After and the raw response before retrying.

04Invalid parameters

Confirm the model, image type, size, and video duration. Ignored optional fields are listed in the response headers.

055xx or timeout

Media jobs can be long-running. Check gateway logs by request ID; use Docker if an edge runtime deadline is too short.

FAQ

Straight answers

01Is this an official Agnes AI project?

No. It is an independent, open-source compatibility gateway built against the public Agnes API documentation.

02Does the gateway store my API key?

No. Production has no server-side key. This tester keeps your key in memory only and sends it with each request.

03Which models are supported?

The gateway does not maintain a model catalog or aliases. Supply any model name your Agnes account supports.

04Why can a response differ from OpenAI?

Some Agnes capabilities have no exact OpenAI equivalent. The compatibility matrix documents every pass-through, conversion, and partial behavior.

05Can I self-host it?

Yes. Deploy it to Deno Deploy or run the multi-architecture Docker image.

06How do I report a compatibility issue?

Open a GitHub issue with the route, redacted request, response status, and request ID. Never include your API key.