API Gateway

https://gateway.agentsky.dev serves the Anthropic Messages API, the OpenAI Chat Completions, Responses and Embeddings APIs, and the decisions API behind one AgentSky key, plus APIs for search, maps, email, speech, transcription, SEO data and image generation (the run API). Every completed model call is billed; the charge appears inline on most responses and is always retrievable via GET /v1/generation.

Base URLs#

Authenticate with an AgentSky API key (ast_…, created under Developer → API keys) as x-api-key or Authorization: Bearer. Model calls and runs need the write scope; catalog and account reads need read.

Routes#

Model ids#

Use the catalog id (anthropic/claude-sonnet-5, qwen/qwen-max), an accepted alias (glm/glm-5.2, kimi/k3), or the bare id (claude-sonnet-5). A vendor prefix that matches nothing is a 404.

Anthropic compatibility#

Messages supports JSON and streaming responses. Token counting is available for active Anthropic resources whose IDs end in -anthropic-api; it requires read scope and does not charge the wallet. Other resource routes may have different endpoint support.

Send anthropic-version on GET /v1/models to receive the Anthropic SDK list format (data, has_more, first_id, last_id), with limit, before_id, and after_id pagination. Retrieve a model with GET /v1/models/{id} and the same anthropic-version header; URL-encode the full model ID when it contains a slash. Without this header, the endpoint returns the AgentSky catalog with prices. Unknown model capability metadata is returned as null.

On Anthropic responses, request-id preserves the upstream request identifier when one is supplied and valid. Gateway-generated errors and Models responses use a gateway identifier instead. x-agentsky-request-id remains the separate AgentSky support reference; include both identifiers when reporting a problem. A request ID or thinking signature alone does not establish a direct connection to Anthropic.

For Messages requests to anthropic/claude-fable-5-1-anthropic-api, use thinking: {"type": "adaptive"} and output_config.effort to control reasoning. Explicit thinking.type values of disabled or enabled are not supported on this resource.

Message Batches (/v1/messages/batches) is not currently supported. Batch pricing and any batch discount are not offered by this gateway at this time.

Decision models#

A decision model answers typed questions about supplied state instead of generating text, so it is served on /api/alpha/decisions rather than the chat paths — the catalog marks it "type": "decision" with "wires": ["decisions"]. Send {model, state, questions}, where each named question is {type: "noul" | "choice" | "score", instructions, criteria?}; the reply carries an answer with a probability per question. A chat model on this path is a 404, as is a decision model on the chat paths. The wire does not stream: stream: true is a 400. Errors use {"error":{"code","message"}}.

Failover#

A model may be served from more than one place. The gateway tries them in its own order and fails over to the next when one is unreachable, times out before the first byte, or answers 408, 429, 401, 403 or 5xx; any other reply is returned as-is, and nothing is retried once response bytes have been sent. Which upstream serves a call is platform configuration, not a request option: OpenRouter's provider body field and Vercel's providerOptions.gateway are accepted and dropped before forwarding.

Cost in the response#

Model calls: usage.cost (USD) on the final usage object — the usage-only last chunk of an OpenAI Chat Completions stream, response.completed on the Responses API, message_delta on the Anthropic wire, or the JSON body. Responses API streams ending in response.incomplete or response.failed are billed when they carry usage, but those terminal events are relayed without a usage.cost field; use GET /v1/generation?id=<response id> to retrieve the charge. Runs: price.amount.value is the customer charge in price.amount.currency (USD). The public billing cost fields have null values; they do not expose supplier costs. A RUNNING run may report zero before settlement; this is not a final price or a free generation. Prices are per token or per unit as listed in the catalog; GET /v1/generation?id=<upstream id or call id> returns the record once it has landed.

Runs#

POST /v1/run
{ "provider": "exa", "endpoint": "search", "input": { "query": "agent gateways", "numResults": 5 } }

200 { "runId": "run_…", "status": "COMPLETED", "provider": "exa", "endpoint": "search",
      "output": { … vendor response … },
      "price": { "type": "PER_CALL", "amount": { "value": 0.014, "currency": "USD" } },
      "providerResponse": { "httpStatus": 200 }, … }

A request can return a completed run, or a saved run with status: RUNNING. Image and video generation can outlast the HTTP connection. A network timeout, HTML error page, or other non-JSON response does not tell you whether generation succeeded. Read GET /v1/runs/{runId} until the status is COMPLETED, FAILED, or TIMED_OUT; use a key with both read and write scopes.

Send an Idempotency-Key on the first POST. Save it, the exact request body, and any returned runId before retrying. If you lost the run ID, send GET /v1/runs/by-idempotency with the same API token and original Idempotency-Key; it requires read scope and never starts another supplier request. A 404 means no saved run is visible yet, so keep the original key and retry the read; a missing or malformed key is 400. The response is private and not cached. You can also repeat the POST with the same API key, idempotency key, and body to retrieve the existing run; that path may create a run if the first POST never arrived. Reusing the key with a different body returns 409 idempotency_conflict. Use a new key only for an intentionally new generation. Do not rotate keys or automatically submit a fresh paid request after a timeout.

Node.js example: submit, recover, and poll

Save this as run.mjs and run it with Node.js 22 or later. Set AGENTSKY_API_KEY and AGENTSKY_IDEMPOTENCY_KEY in your environment. Choose a unique idempotency key for this generation and keep it unchanged when restarting this script. Set RUN_ID to resume a known run directly. This example stops waiting after 30 minutes without cancelling the server-side job.

const apiKey = process.env.AGENTSKY_API_KEY;
const idempotencyKey = process.env.AGENTSKY_IDEMPOTENCY_KEY;
if (!apiKey || !idempotencyKey) {
  throw new Error("Set AGENTSKY_API_KEY and a saved AGENTSKY_IDEMPOTENCY_KEY");
}
const baseUrl = "https://gateway.agentsky.dev";
const body = JSON.stringify({
  provider: "openai",
  endpoint: "gpt-image-2",
  input: { prompt: "A red bicycle on a white background", quality: "low" },
});
let runId = process.env.RUN_ID;
const deadline = Date.now() + 30 * 60 * 1000;
let finished = false;

while (Date.now() < deadline) {
  let response;
  let run;
  try {
    response = await fetch(runId ? baseUrl + "/v1/runs/" + encodeURIComponent(runId) : baseUrl + "/v1/run", {
      method: runId ? "GET" : "POST",
      headers: {
        Authorization: "Bearer " + apiKey,
        "Content-Type": "application/json",
        ...(runId ? {} : { "Idempotency-Key": idempotencyKey }),
      },
      ...(runId ? {} : { body }),
      signal: AbortSignal.timeout(Math.min(180_000, deadline - Date.now())),
    });
    run = await response.json();
  } catch {
    if (response && response.status >= 400 && response.status < 500 && response.status !== 408 && response.status !== 429) {
      throw new Error("HTTP " + response.status + "; keep the saved request and key for investigation");
    }
    await new Promise(resolve => setTimeout(resolve, 5000));
    continue;
  }
  if (run.runId) {
    runId = run.runId;
    console.log("Save runId:", runId);
    if (run.status === "COMPLETED") {
      console.log("Output:", run.output);
      console.log("Customer charge:", run.price.amount);
      finished = true;
      break;
    }
    if (run.status === "FAILED" || run.status === "TIMED_OUT") {
      throw new Error(JSON.stringify({ runId, status: run.status, error: run.error, price: run.price }));
    }
  } else if (!response.ok && response.status !== 408 && response.status !== 429 && response.status < 500) {
    throw new Error(JSON.stringify(run.error ?? run));
  } else if (response.ok) {
    throw new Error("Unexpected response; retain the same request and idempotency key");
  }
  await new Promise(resolve => setTimeout(resolve, 5000));
}
if (!finished) {
  throw new Error("Still unresolved. Resume with the same saved key/body or RUN_ID=" + (runId ?? "unknown"));
}

A terminal failure includes error: { code, message }. An HTTP failure or connection timeout does not establish the run outcome or charge: a pending generation can still complete and settle. Retrieve the saved run and check its terminal status and price.amount; keep the run ID for reconciliation. Do not treat a pending zero amount as final or start a new generation merely because the connection failed.

Reading image and video outputs

The output object follows the endpoint's response shape; there is no universal binary wrapper. Check the endpoint reference and select the appropriate field after COMPLETED:

For a GPT image, save Buffer.from(run.output.data[0].b64_json, "base64") using Node's writeFile; use the returned format or MIME type for the file extension. For URL outputs, download the returned URL promptly and save the response bytes. Gateway media URLs contain a signed token valid for one hour: keep them private. Reading the run again issues a fresh link while the saved run and underlying media remain available; this does not guarantee permanent storage of the provider's media.

Errors#

Errors take the shape of the wire: Anthropic { "type": "error", "error": { "type", "message" } }, OpenAI { "error": { "message", "type", "param", "code" } }, and { "error": { "code", "message" } } on run and account routes. Codes you will see: model_not_found, endpoint_not_found, pricing_unavailable (503, the SKU has no rate yet), upstream_unavailable, insufficient_credits / insufficient_quota (spend gate), rate_limited.

Limits#

Request bodies up to 10 MB on the model wires and 1 MB on most APIs (35 MB for audio uploads). Media outputs up to 20 MB inline. Per-key rate limits apply.