AI connections and gateway

Connect an OpenRouter key to your project

1. Prepare your OpenRouter key

   Create an API key on the OpenRouter website. Browse models and copy the ID of a model that supports the task you want to use.

2. Open the AI connection tab

   Select a project and save the key on its AI connection tab. Project owners and editors can add or replace the key, or disconnect to remove it.

3. Call from server code

   Once you save the key, your server code can use env.OPENROUTER_API_KEY and env.AI_GATEWAY. No gateway URL is needed.

AI requests use the OpenRouter key you registered. The key is stored as a Secret on your project Worker, and you cannot view its value after saving. Save a new key to replace it, or disconnect to delete it. Keep the key out of browser code, Git, logs and conversations with your coding agent.

run(model, input, options)

Call env.AI_GATEWAY.run() from your project’s server code. The examples below belong inside a Hono request handler, after you have checked the user’s login and permissions. Each example uses c.env to access the project’s bindings.

const response = await env.AI_GATEWAY.run(model, input, { apiKey, task });

model · required

An OpenRouter model ID that supports the selected task. Replace the model ID placeholders below with real IDs.

input · required

An object containing the model’s input. Put chat messages in messages, text to embed in input, or an image description in prompt.

options.apiKey · required

Pass your saved key as env.OPENROUTER_API_KEY.

options.task · required

Set this to chat, embeddings or image. If it is missing or has another value, the gateway returns 400 without sending a request to OpenRouter.

Return value

Returns a Response object. Forward streaming responses directly. For JSON responses, check response.ok before calling response.json().

Chat and streaming

Choose a chat model and put the conversation in messages. Set stream: true to receive the answer as an SSE stream. Return the response directly rather than reading it with response.json().

const env = c.env;
const response = await env.AI_GATEWAY.run(
  "<CHAT_MODEL_ID>",
  {
    messages: [{ role: "user", content: "Hello" }],
    stream: true,
  },
  { apiKey: env.OPENROUTER_API_KEY, task: "chat" },
);
return response;

Text embeddings

Choose an embedding model and pass a string or an array of strings in input. If the request succeeds, the JSON response contains vectors in data[].embedding. Your app is responsible for storing the vectors and source text and using them for search.

const env = c.env;
const response = await env.AI_GATEWAY.run(
  "<EMBEDDING_MODEL_ID>",
  { input: ["Hello", "World"] },
  { apiKey: env.OPENROUTER_API_KEY, task: "embeddings" },
);
return response;

Image generation

Choose a model supported by the OpenRouter Image API and describe the image in prompt. This example requests one image. Once generation finishes, the JSON response contains a Base64-encoded image in data[].b64_json. If media_type is present, it identifies the image format. Check the OpenRouter image generation docs for model-specific options.

const env = c.env;
const response = await env.AI_GATEWAY.run(
  "<IMAGE_MODEL_ID>",
  { prompt: "A cat sitting by a sunny window", n: 1 },
  { apiKey: env.OPENROUTER_API_KEY, task: "image" },
);
return response;

Handle errors and control access

• The gateway returns 400 if task is missing or unsupported, the model ID is empty or is not a string, or the input is not an object.
• A missing or malformed API key returns 401. If OpenRouter returns an error, the gateway keeps its HTTP status and includes upstream_status and a short error message in the response.
• If the gateway cannot connect to OpenRouter, it returns 502. Binding calls can also throw exceptions, so handle these in your app’s error handling code.
• Use the API key only on the server. Check the login and permissions of users who call AI features in your app, and set request limits where needed. The project’s AI connection settings do not check those users’ permissions for you.
• Keep keys, prompts and raw AI responses out of logs. A streaming request can fail after the HTTP response has started, so check for error messages while your app reads the stream.

See the app authentication and authorization guide and your project’s AI connection tab.