HTTP API

Base URL: https://ai-gateway.bijection.com. To send a request from an action, see Getting started.

Authentication

Authorization: Bearer <token>

Get the token in an action with getServiceToken("ai-gateway"). The action runtime caches and refreshes it as needed. Token rules and errors: Getting started. Missing or invalid token:

{
  "error": {
    "message": "Invalid authentication credentials",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

GET `/v1/models`

No query parameters or body.

{
  "object": "list",
  "data": [
    {
      "id": "openai/gpt-4o-mini",
      "object": "model",
      "created": 1715620800,
      "owned_by": "openai"
    }
  ]
}

owned_by is the provider prefix of id.

POST `/v1/chat/completions`

OpenAI Chat Completions body. Set stream: true for SSE.

Field	Type	Required	Description
model	string	y	`provider/model` id
messages	array	y	OpenAI messages
stream	boolean	n	SSE when `true`. Defaults to `false`

Other OpenAI fields (temperature, max_tokens, tools, response_format, …) are forwarded. Body must be JSON, max 16 MiB. These fields are rejected. Bijection chooses how the request is served: provider, route, models, transforms, plugins, preset.

{
  "error": {
    "message": "The `provider` parameter is not supported. Bijection selects how a request is served.",
    "type": "invalid_request_error",
    "code": "unsupported_parameter",
    "param": "provider"
  }
}

Response

id is assigned by Bijection. Non-streaming is application/json:

{
  "id": "3f1c8a2e-9b14-4d6a-a7e2-0c5b8d1e4f90",
  "object": "chat.completion",
  "created": 1715367049,
  "model": "openai/gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Hello!" },
      "finish_reason": "stop",
      "logprobs": null
    }
  ],
  "system_fingerprint": "fp_123",
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 5,
    "total_tokens": 17,
    "prompt_tokens_details": { "cached_tokens": 0 },
    "completion_tokens_details": { "reasoning_tokens": 0 }
  }
}

Streaming is text/event-stream. Chunks use "object": "chat.completion.chunk" and choices[].delta instead of choices[].message:

data: {"id":"3f1c8a2e-9b14-4d6a-a7e2-0c5b8d1e4f90","object":"chat.completion.chunk","created":1715367049,"model":"openai/gpt-4o-mini","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: [DONE]

Retry-After is forwarded when present.

POST `/v1/embeddings`

OpenAI Embeddings body. model and input are required. input may be one string, one token-ID array, or a batch of up to 512 strings or token-ID arrays. Other OpenAI fields are forwarded. The body must be JSON and no larger than 16 MiB. Bijection rejects the same routing controls as /v1/chat/completions, assigns the response id, and removes fields that identify the serving provider. The response otherwise uses the OpenAI embeddings shape.

POST `/v1/images/generations`

Image generation is in alphaThe request and response format may change during alpha.

Send a JSON body with model and prompt, plus model-supported image options such as size and n. The response contains data entries with image URLs or b64_json, depending on the model and requested format. Streaming is rejected. The same routing controls as /v1/chat/completions are rejected. The body limit is 16 MiB.

POST `/v1/videos/generations`

Video generation is in alphaThe request and response format may change during alpha.

Send model and prompt, with optional duration, aspect_ratio, size, resolution, seed, generate_audio, frame_images, or input_references. Supported values depend on the model. Each request generates one video; n, stream, and callback_url are rejected, along with gateway routing controls. The body limit is 16 MiB. This request waits for completion and downloads the video, with a default ten-minute timeout and a 64 MiB video limit. The JSON response contains a Bijection-assigned id, data: [{ b64_json, media_type }], and usage when available. Cancelling the HTTP request does not cancel generation or its cost.

Async video routes

These routes are in alpha. For availability and local development, see Async videos. All three routes require a deployment token. Save the opaque operation value returned at submission and use a fresh token from the same deployment for later requests. Operations expire after seven days; video retention may be shorter.

POST `/v1/videos`

Accepts the same generation options as /v1/videos/generations, plus an optional webhook_url on the deployment’s HTTPS <deployment>.bijection.site origin. Returns HTTP 202:

{
  "id": "bijection-inference-id",
  "operation": "opaque-operation-handle",
  "webhook_secret": "per-job-signing-secret"
}

webhook_secret is null when webhook_url is omitted. Store it privately. A lost response can still mean the job was accepted and charged; automatically retrying submission can create another paid job.

POST `/v1/videos/status`

Send { "operation": "opaque-operation-handle" }. Returns status as pending, completed, or error, with an error message for failed jobs and usage when available.

POST `/v1/videos/download`

Send the same operation body. Returns the video in the same data shape as /v1/videos/generations. Returns 409 if the video is not ready. Each call fetches the video again; save it in application storage.

Application callbacks

The gateway posts a signed JSON event to webhook_url with id, operation, status, and type (video.generation.<status>). Terminal statuses are completed, failed, cancelled, and expired. Verify the raw body and x-bijection-video-signature header with verifyVideoWebhook before changing application state. Match the event’s id to the saved inference ID, and deduplicate by (id, status) when saving it. See receiving a callback. Callbacks can repeat; check unfinished jobs periodically as a fallback.

POST `/alpha/decisions`

Decisions is in alphaThe request and response format may change during alpha.

Jev is TypeSafe’s model for making structured decisions. It returns values your code can use to choose an option, rank results, or decide what to do next. Provide the context to evaluate in state and the questions to answer in questions. You can ask several questions about the same state in one request. Each question is evaluated independently and has a name that identifies its answer in the response. model, state, and questions are required. Use typesafe/jev-1.13 as the model ID; Decisions models are not listed by GET /v1/models. Streaming is not supported. With the AI SDK provider, use evaluate({ model: bijectionGateway.evaluationModel("typesafe/jev-1.13"), ... }). The SDK calls the yes-or-no question type boolean and returns probability; the HTTP API uses noul for both. For example, classify a support ticket by priority:

{
  "model": "typesafe/jev-1.13",
  "state": {
    "ticket": "All users are unable to sign in. There is no workaround."
  },
  "questions": {
    "priority": {
      "type": "choice",
      "instructions": "Choose the support ticket's priority.",
      "criteria": {
        "urgent": "An outage is blocking users.",
        "normal": "A bug affects users but has a workaround."
      }
    }
  }
}

state and each question’s instructions accept a string, object, or array. Each question must specify one of these types:

`type`	Purpose	Required fields	Result field
`choice`	Select an option	`instructions`, `criteria` map	`choice`
`score`	Evaluate the state against a rubric	`instructions`, `criteria` array	`score`
`noul`	Evaluate whether a statement is true	`instructions`	`noul`, a number from 0–1

Keep each question focused on one decision. For decisions involving several factors, ask about each factor separately and combine the answers in your code. A noul question may include criteria with true and false guidance. Choice criteria values may be strings, objects, arrays, or null. Score criteria are an ordered array of strings, objects, or arrays. The body must be JSON and no larger than 16 MiB. These fields are not supported: provider, route, models, transforms, plugins, preset, fallbacks, speed, trace, session_id, user, and stream.

Response

The answer keys match the request’s question keys. Bijection assigns id and removes fields that identify the serving provider. choice and score answers may also include confidence and probabilities.

{
  "id": "3f1c8a2e-9b14-4d6a-a7e2-0c5b8d1e4f90",
  "model": "typesafe/jev-1.13",
  "answers": {
    "priority": {
      "type": "choice",
      "choice": "urgent",
      "confidence": 0.9,
      "probabilities": { "urgent": 0.9, "normal": 0.1 }
    }
  },
  "usage": {
    "input_tokens": 21,
    "output_tokens": 3,
    "cost": 0.0042
  }
}

usage contains the input and output token counts. usage.cost, when present, is the request cost in US dollars.

POST `/v1/messages`

Anthropic Messages body. Model IDs use the provider/model form. model, messages, and max_tokens are required. Set stream: true for Anthropic-compatible server-sent events.

{
  "model": "anthropic/claude-haiku-4.5",
  "max_tokens": 128,
  "messages": [{ "role": "user", "content": "Hello!" }]
}

Other Anthropic fields are forwarded. The body must be JSON and no larger than 16 MiB. These OpenRouter routing controls are rejected because Bijection chooses how the request is served: provider, route, models, plugins, fallbacks, session_id, and speed. The response uses the Anthropic Messages shape. Bijection replaces upstream id and request_id values with Bijection-generated IDs and removes fields that identify the serving provider. Local errors, including authentication errors, also use the Anthropic error shape:

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid authentication credentials"
  },
  "request_id": "3f1c8a2e-9b14-4d6a-a7e2-0c5b8d1e4f90"
}

POST `/v1/responses`

OpenAI Responses body. Model IDs use the provider/model form. model and input are required. Set stream: true for server-sent events.

{
  "model": "openai/gpt-5-mini",
  "input": "Hello!"
}

Other OpenAI Responses fields are forwarded. The body must be JSON and no larger than 16 MiB. These OpenRouter routing controls are rejected because Bijection chooses how the request is served: provider, route, models, transforms, plugins, preset, and session_id. The endpoint is stateless. OpenRouter rejects store: true and a non-null previous_response_id. Bijection replaces upstream response IDs with Bijection-generated IDs and removes fields that identify the serving provider. Caller-supplied metadata on a response is preserved.

Errors

Status	code	When
401	`invalid_api_key`	Missing or invalid `Authorization`
400	`unsupported_endpoint`	Unknown path
400	`unsupported_parameter`	Rejected routing field
400	`too_many_inputs`	Over 512 embedding inputs
413	`request_too_large`	Body over 16 MiB
502 / 503	`upstream_error`	Provider temporarily unavailable

Provider validation errors (unknown model, bad args) keep the provider status. The error object has message, type, code, and param when present.

Get Started

Platform

Data and Operations

Guides

Client Libraries

Tools

API Reference

Authentication

GET `/v1/models`

POST `/v1/chat/completions`

Response

POST `/v1/embeddings`

POST `/v1/images/generations`

POST `/v1/videos/generations`

Async video routes

POST `/v1/videos`

POST `/v1/videos/status`

POST `/v1/videos/download`

Application callbacks

POST `/alpha/decisions`

Response

POST `/v1/messages`

POST `/v1/responses`

Errors

​Authentication

​GET /v1/models

​POST /v1/chat/completions

​Response

​POST /v1/embeddings

​POST /v1/images/generations

​POST /v1/videos/generations

​Async video routes

​POST /v1/videos

​POST /v1/videos/status

​POST /v1/videos/download

​Application callbacks

​POST /alpha/decisions

​Response

​POST /v1/messages

​POST /v1/responses

​Errors

Authentication

GET `/v1/models`

POST `/v1/chat/completions`

Response

POST `/v1/embeddings`

POST `/v1/images/generations`

POST `/v1/videos/generations`

Async video routes

POST `/v1/videos`

POST `/v1/videos/status`

POST `/v1/videos/download`

Application callbacks

POST `/alpha/decisions`

Response

POST `/v1/messages`

POST `/v1/responses`

Errors