API reference

// Body of POST /api/v1/chat/completions and POST /api/v1/images.
type Request = {
  // Required. A catalogue identifier, exactly as listed: "vendor/model".
  // Unknown or missing -> 404. Listed but not served yet -> 400.
  // The catalogue decides what the model answers with: text or a frame.
  model: string;

  // chat/completions: the whole conversation is read, not just the last turn.
  messages?: Message[];

  // images: an explicit prompt, plus the frames to work from (up to 16).
  prompt?: string;
  input_references?: (string | ImageContentPart)[];

  stream?: boolean;       // default false
  n?: number;             // image models: frames per request, 1..10; text models: 1

  // -- Text models on chat/completions --------------------------------------
  max_tokens?: number;    // ceiling on the reply; not sent -> 4096
  temperature?: number;   // removed silently on models that refuse it
  top_p?: number;         // same
  top_k?: number;
  stop?: string | string[];
  tools?: Tool[];
  tool_choice?: 'auto' | 'none' | 'required'
    | { type: 'function'; function: { name: string } };
  parallel_tool_calls?: boolean;
  stream_options?: { include_usage?: boolean };  // accepted; usage is sent anyway
  cache_control?: { type: 'ephemeral'; ttl?: string }; // automatic prompt caching

  // -- Image models ---------------------------------------------------------
  size?: string;          // "1080x1920" | "2K" | "auto"
  resolution?: string;    // same values as size
  image_size?: string;    // same values as size
  aspect_ratio?: string;  // "9:16", "16:9", "1:1", "9:19.5", ...
  quality?: 'auto' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';  // provider default
  output_format?: 'png' | 'jpeg' | 'webp';
  output_compression?: number;                    // 0..100, jpeg and webp only
  background?: 'auto' | 'transparent' | 'opaque';
  // The image fields above may also be sent nested here. Both places are
  // read, and every value sent is validated, not just the first one found.
  image_config?: Record<string, unknown>;

  // Accepted, and deliberately not acted on. On a text model the same goes
  // for response_format, logit_bias, logprobs and the two penalties.
  seed?: number;
  user?: string;
};

// Subtypes:

type TextContentPart = { type: 'text'; text: string; cache_control?: CacheControl };

type ImageContentPart = {
  type: 'image_url';
  image_url: { url: string };   // https://... or data:image/png;base64,...
  cache_control?: CacheControl;
};

type CacheControl = { type: 'ephemeral'; ttl?: string };

type Message =
  // "system" and "developer" are the standing instruction: an image model
  // reads them first, a text model gets them as its system prompt.
  | { role: 'system' | 'developer'; content: string | TextContentPart[] }
  | { role: 'user'; content: string | (string | TextContentPart | ImageContentPart)[] }
  // Earlier answers of a text model, tool calls included.
  | { role: 'assistant'; content?: string | TextContentPart[]; tool_calls?: ToolCall[] }
  // The result of a tool call, matched by id.
  | { role: 'tool'; tool_call_id: string; content: string | TextContentPart[] };

type Tool = {
  type: 'function';
  function: { name: string; description?: string; parameters?: object };
};

type ToolCall = {
  id: string;
  type: 'function';
  function: { name: string; arguments: string };   // arguments is a JSON string
};

const r = await fetch('https://api.gtokens.io/api/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk-sl-your-key',   // required on every route
    'Content-Type': 'application/json',       // required on every POST
  },
  body: JSON.stringify({
    model: 'anthropic/claude-sonnet-5',
    messages: [{ role: 'user', content: 'Describe a lighthouse at dawn' }],
    max_tokens: 256,
  }),
})

// POST /api/v1/chat/completions
type Response = {
  id: string;        // "gen-...", the identifier this request is logged under
  object: 'chat.completion' | 'chat.completion.chunk';
  created: number;   // unix seconds
  model: string;     // the catalogue identifier you asked for
  // Always an array with one element. It carries "message", or "delta"
  // instead when stream: true was sent.
  choices: Choice[];
  usage: Usage;      // always present, never zeroed
};

type Choice = {
  index: 0;
  // Image models: always "stop". Text models: one of the four; null on every
  // streamed chunk except the last.
  finish_reason: 'stop' | 'length' | 'tool_calls' | 'content_filter' | null;
  // Text models: the executor's own word for it, e.g. "end_turn", "max_tokens".
  native_finish_reason?: string;
  message?: AssistantMessage;
  delta?: Partial<AssistantMessage>;
};

type AssistantMessage = {
  role: 'assistant';
  content: string;          // the answer of a text model; "" for an image model
  tool_calls?: ToolCall[];  // text models, when the model calls a tool
  images?: ImageOut[];      // image models: the frames
};

// The frame itself: a data URL, ready to decode or to hand to a browser.
type ImageOut = { type: 'image_url'; image_url: { url: string } };

type Usage = {
  prompt_tokens: number;      // text models: cached input included
  completion_tokens: number;
  total_tokens: number;
  cost: number;               // US dollars charged for this request
  prompt_tokens_details?: { cached_tokens: number };  // when a cache was read
};

// POST /api/v1/images returns the same usage in a different envelope.
type ImagesResponse = {
  created: number;
  data: { b64_json: string; media_type: string }[];
  usage: Usage;
};

{
  "id": "gen-3b7e9c1d5a2f4086",
  "object": "chat.completion",
  "created": 1772668800,
  "model": "anthropic/claude-sonnet-5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "A lighthouse at dawn stands pale against a sky just turning gold. Its beam, still lit, fades as the sun takes over."
      },
      "finish_reason": "stop",
      "native_finish_reason": "end_turn"
    }
  ],
  "usage": {
    "prompt_tokens": 26,
    "completion_tokens": 58,
    "total_tokens": 84,
    "cost": 0.000316
  }
}