API Reference — every endpoint, params & examples

conventions · true everywhere

Base URLhttps://defai.gtio.work/v1 (OpenAI surfaces) · https://defai.gtio.work (Anthropic Messages) · https://defai.gtio.work/vertex-ai (Google Vertex)

AuthAuthorization: Bearer sk-relay-… on every request — one key spends one balance across all surfaces.

ModelsAddressed as provider/model (e.g. openai/gpt-5.5). Pull the live catalog from GET /v1/models.

ErrorsJSON envelope { error: { message, type, request_id } }; branch on status — 401 key · 402 balance · 404 model · 429 rate · 502 upstream.

POST/v1/chat/completionsOpenAI

Chat Completions

The OpenAI Chat Completions API — the default surface for text, vision, and tool use. Address any model as provider/model.

request	type	description
model required	string	e.g. openai/gpt-5.5, anthropic/claude-opus-4.8.
messages required	array	Conversation as [{role, content}]; role is system \| user \| assistant \| tool. content may be a string or content parts (text/image).
stream optional	boolean	Stream Server-Sent Events with token deltas. Default false.
max_completion_tokens optional	integer	Cap on generated tokens (legacy alias: max_tokens).
temperature optional	number	0–2. Sampling temperature.
top_p optional	number	0–1. Nucleus sampling.
reasoning_effort optional	string	none \| minimal \| low \| medium \| high \| xhigh — thinking depth (the supported set is model-dependent).
tools / tool_choice optional	array / string	Function/tool definitions and selection.
response_format optional	object	{ "type": "json_object" \| "json_schema", … } for structured output.
stop, n, seed, frequency_penalty, presence_penalty optional	mixed	Standard OpenAI sampling controls.

response	type	description
id optional	string	Completion id.
choices[].message.content optional	string	The assistant's reply.
choices[].finish_reason optional	string	stop \| length \| tool_calls \| …
usage optional	object	prompt_tokens, completion_tokens, total_tokens; prompt_tokens_details.cached_tokens and completion_tokens_details.reasoning_tokens when present.

request

curl https://defai.gtio.work/v1/chat/completions \
  -H "Authorization: Bearer sk-relay-…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.5",
    "messages": [{"role": "user", "content": "Settle this."}],
    "stream": false
  }'

response

{
  "id": "chatcmpl-…",
  "choices": [{"index": 0, "message": {"role": "assistant", "content": "…"}, "finish_reason": "stop"}],
  "usage": {"prompt_tokens": 7, "completion_tokens": 42, "total_tokens": 49,
            "prompt_tokens_details": {"cached_tokens": 0}}
}

POST/v1/messagesAnthropic

Anthropic Messages

The Anthropic Messages API — what Claude Code speaks. The relay injects anthropic-version (forward your own to override) and passes anthropic-beta opt-ins through.

header	type	description
anthropic-version optional	header	2023-06-01 (defaulted by the relay if omitted)
anthropic-beta optional	header	optional opt-ins, e.g. extended prompt caching

request	type	description
model required	string	e.g. anthropic/claude-opus-4.8.
max_tokens required	integer	Required by Anthropic — max tokens to generate.
messages required	array	[{role, content}]; role is user \| assistant. content is a string or content blocks (text/image).
system optional	string \| array	System prompt. Add cache_control on a block to cache it.
temperature, top_p, top_k optional	number	Sampling controls.
stream optional	boolean	Stream SSE (message_start / content_block_delta / message_delta).
stop_sequences, tools optional	array	Stop strings and tool definitions.

response	type	description
content[].text optional	string	Generated text blocks.
stop_reason optional	string	end_turn \| max_tokens \| stop_sequence \| tool_use.
usage optional	object	input_tokens, output_tokens, cache_read_input_tokens, cache_creation_input_tokens (5-min / 1-h).

request

curl https://defai.gtio.work/v1/messages \
  -H "Authorization: Bearer sk-relay-…" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-opus-4.8",
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "Settle this."}]
  }'

response

{
  "type": "message", "role": "assistant",
  "content": [{"type": "text", "text": "…"}],
  "stop_reason": "end_turn",
  "usage": {"input_tokens": 9, "output_tokens": 42,
            "cache_read_input_tokens": 0, "cache_creation_input_tokens": 0}
}

POST/v1/responsesOpenAI

Responses API

The OpenAI Responses API — the surface newer Codex uses. When streaming, usage arrives in the terminal response.completed frame.

request	type	description
model required	string	e.g. openai/gpt-5.5.
input required	string \| array	A prompt string, or structured input items.
max_output_tokens optional	integer	Cap on output tokens.
instructions optional	string	System-level instructions.
reasoning optional	object	{ "effort": "low" \| "medium" \| "high" }.
temperature, top_p, stream, tools optional	mixed	Sampling, streaming, and tools.

response	type	description
output[].content[].text optional	string	Output text items.
status optional	string	completed \| incomplete \| …
usage optional	object	input_tokens, output_tokens, total_tokens; output_tokens_details.reasoning_tokens.

request

curl https://defai.gtio.work/v1/responses \
  -H "Authorization: Bearer sk-relay-…" \
  -H "Content-Type: application/json" \
  -d '{"model": "openai/gpt-5.5", "input": "Settle this.", "max_output_tokens": 256}'

response

{
  "object": "response", "status": "completed",
  "output": [{"type": "message", "content": [{"type": "output_text", "text": "…"}]}],
  "usage": {"input_tokens": 8, "output_tokens": 24, "total_tokens": 32}
}

POST/v1/embeddingsOpenAI

Embeddings

Vector embeddings for text. Returns a float array per input.

request	type	description
model required	string	e.g. openai/text-embedding-3-small.
input required	string \| array	One string or an array of strings to embed.
dimensions optional	integer	Optional output dimension (model-dependent).
encoding_format optional	string	float (default) \| base64.

response	type	description
data[].embedding optional	number[]	The embedding vector.
usage optional	object	prompt_tokens, total_tokens.

request

curl https://defai.gtio.work/v1/embeddings \
  -H "Authorization: Bearer sk-relay-…" \
  -H "Content-Type: application/json" \
  -d '{"model": "openai/text-embedding-3-small", "input": "hello world"}'

response

{
  "data": [{"index": 0, "embedding": [0.0021, -0.013, …]}],
  "usage": {"prompt_tokens": 2, "total_tokens": 2}
}

POST/v1/images/generationsOpenAI

Image Generation

OpenAI-compatible text-to-image for gpt-image models. Returns base64 PNGs. (Imagen / Gemini image models use the Vertex surface below.)

request	type	description
model required	string	An OpenAI image model, e.g. openai/gpt-image-2.
prompt required	string	What to draw.
n optional	integer	Number of images (default 1).
size optional	string	1024x1024 \| 1536x1024 \| 1024x1536 \| auto.
quality optional	string	low \| medium \| high \| auto.

response	type	description
data[].b64_json optional	string	Base64-encoded PNG.
usage optional	object	input_tokens / output_tokens with image/text token details.

request

curl https://defai.gtio.work/v1/images/generations \
  -H "Authorization: Bearer sk-relay-…" \
  -H "Content-Type: application/json" \
  -d '{"model": "openai/gpt-image-2", "prompt": "an isometric neon terminal", "size": "1024x1024"}'

response

{ "data": [{"b64_json": "iVBORw0KG…"}],
  "usage": {"input_tokens": 13, "output_tokens": 196,
            "output_tokens_details": {"image_tokens": 196}} }

POST/v1/images/editsOpenAI

Image Editing (image-to-image)

Edit or extend an image from a reference (and optional mask). multipart/form-data, not JSON.

header	type	description
Content-Type optional	header	multipart/form-data

request	type	description
model required	form field	An OpenAI image model, e.g. openai/gpt-image-2.
image required	file	The source image (PNG).
prompt required	form field	How to edit it.
mask optional	file	Optional transparency mask for local edits.
n, size optional	form field	Count and output size.

response	type	description
data[].b64_json optional	string	Base64 PNG of the edited image.

request

curl https://defai.gtio.work/v1/images/edits \
  -H "Authorization: Bearer sk-relay-…" \
  -F model="openai/gpt-image-2" \
  -F image="@input.png" \
  -F prompt="tint it green"

response

{ "data": [{"b64_json": "iVBORw0KG…"}],
  "usage": {"input_tokens": 1035, "input_tokens_details": {"image_tokens": 1024, "text_tokens": 11},
            "output_tokens": 229, "output_tokens_details": {"image_tokens": 229}} }

GET/v1/modelsOpenAI

List Models

The full callable catalog, with modality and the surfaces (suitable_api) each model accepts.

response	type	description
data[].id optional	string	provider/model identifier.
data[].input_modalities / output_modalities optional	string[]	text, image, video, audio, file, embeddings.
data[].suitable_api optional	string[]	chat.completions, messages, responses, images, imagen, gemini, veo, embeddings.
data[].billing optional	string	token \| image \| video — how it's metered.

request

curl https://defai.gtio.work/v1/models -H "Authorization: Bearer sk-relay-…"

response

{ "object": "list", "data": [
  {"id": "openai/gpt-5.5", "output_modalities": ["text"],
   "suitable_api": ["chat.completions","messages","responses"], "billing": "token"}
]}

POST/vertex-ai/v1/publishers/{publisher}/models/{model}:{method}Google Vertex

Google GenAI / Vertex — image & video

A passthrough to the Google GenAI surface for Imagen, Gemini image, and Veo video. Point the google-genai SDK (vertex mode) at https://defai.gtio.work/vertex-ai with your relay key; it builds these paths for you. The :method tail selects the operation.

method (:tail)	type	description
:predict optional	Imagen	Per-image generation. Body { "instances": [{"prompt": "…"}], "parameters": {"sampleCount": 1} } → { "predictions": [{"bytesBase64Encoded" \| "gcsUri"}] }.
:generateContent optional	Gemini	Image (and text). Body { "contents": [...], "generationConfig": {"responseModalities": ["TEXT","IMAGE"]} } → candidates[].content.parts[].inlineData + usageMetadata.
:predictLongRunning optional	Veo (video)	Async video. Body { "instances": [{"prompt": "…"}], "parameters": {"durationSeconds": 8, "resolution": "720p"} } → an operation name; poll :fetchPredictOperation until done, then read response.videos[].bytesBase64Encoded.

response	type	description
predictions[] / candidates[] / operation optional	varies	By method, as above. Video is retrieved via the operation poll.

python (google-genai)

from google import genai
from google.genai import types

client = genai.Client(
    vertexai=True, api_key="sk-relay-…",
    http_options=types.HttpOptions(base_url="https://defai.gtio.work/vertex-ai", api_version="v1"),
)
# image (imagen)
client.models.generate_images(model="qwen/qwen-image-2.0", prompt="a koi pond")
# video (veo) — async: submit, then poll
op = client.models.generate_videos(
    model="google/veo-3.1-generate-001", prompt="a koi pond",
    config=types.GenerateVideosConfig(duration_seconds=8, resolution="720p"))
while not op.done:
    op = client.operations.get(op)

Mint a key, make the call.

One endpoint, every model and modality. Rates on the pricing page.

Tool setups Launch Console →

Every endpoint, spelled out.

Chat Completions

Anthropic Messages

Responses API

Embeddings

Image Generation

Image Editing (image-to-image)

List Models

Google GenAI / Vertex — image & video