Kove Developer API

All endpoints are HTTPS, accept and return JSON, and are authenticated with a bearer API key created on the API keys tab. Keys are shown once; store them server-side and never ship them to a browser.

Base URL:  https://cowork.fyi/api/public/dev/v1
Header:    Authorization: Bearer kove_sk_...
Header:    Content-Type: application/json

Every request is metered against your prepaid balance. When the balance reaches $0.00 all calls return 402 insufficient_funds until you add funds.

Chat completion. Accepts either a plain input string or an OpenAI-style messages array. Content parts may be text, images, or files — images are read automatically by Kove Vision, and PDFs and text documents are parsed and inlined for you. Image inputs are converted to tokens at 1,000 tokens per megapixel and billed as input tokens. Your system string is appended to the Rohan 3 base prompt rather than replacing it.

curl https://cowork.fyi/api/public/dev/v1/chat \
  -H "Authorization: Bearer $KOVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "system": "Answer as a terse release-notes editor.",
    "temperature": 0.6,
    "messages": [
      { "role": "user", "content": "Summarise this changelog." },
      { "role": "user", "content": [
        { "type": "text", "text": "And describe the screenshot." },
        { "type": "image_url", "image_url": { "url": "data:image/png;base64,iVBORw0..." } },
        { "type": "file", "file": { "filename": "notes.pdf", "file_data": "data:application/pdf;base64,JVBERi0..." } }
      ]}
    ]
  }'

{
  "model": "rohan-3",
  "output": "…",
  "usage": {
    "input_tokens": 1840,
    "output_tokens": 612,
    "image_megapixels": 1.0486,
    "cost_usd": 0.001992
  }
}

Fields: messages (required unless input is given), system, temperature. There is no output cap — Rohan 3 decides its own length, so do not send max_tokens. Images accept a public https URL or a base64 data URL. Files accept a base64 data URL in file_data.

curl https://cowork.fyi/api/public/dev/v1/images \
  -H "Authorization: Bearer $KOVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "an isometric server room, matte render", "size": "square_hd" }'

{
  "model": "kove-image",
  "image": { "url": "https://…", "width": 1024, "height": 1024 },
  "usage": { "megapixels": 1.0486, "cost_usd": 0.031457 }
}

size accepts square_hd (default), landscape_16_9, or portrait_16_9. Returned URLs are temporary — download and store what you need.

curl https://cowork.fyi/api/public/dev/v1/edit-image \
  -H "Authorization: Bearer $KOVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "image_url": "https://example.com/room.jpg", "prompt": "make it night, add warm lamp light" }'

{
  "model": "kove-image-edit",
  "image": { "url": "https://…", "width": 1024, "height": 1024 },
  "usage": { "megapixels": 1.0486, "cost_usd": 0.041943 }
}

image_url accepts a public https URL or a base64 data URL. Describe the change only — the rest of the image is preserved.

curl https://cowork.fyi/api/public/dev/v1/speech \
  -H "Authorization: Bearer $KOVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Deployment finished in four minutes.", "voice": "Olivia" }'

{
  "model": "kove-tts",
  "audio": { "url": "https://…", "content_type": "audio/mpeg", "voice": "Olivia" },
  "usage": { "characters": 36, "cost_usd": 0.0018 }
}

Voices: Clive, Tessa, Olivia, Tyler, Oliver. Maximum 4,000 characters per request — chunk longer scripts client-side.

curl https://cowork.fyi/api/public/dev/v1/youtube \
  -H "Authorization: Bearer $KOVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "how transformers work explained", "limit": 3 }'

{
  "model": "kove-youtube-search",
  "query": "how transformers work explained",
  "results": [
    {
      "id": "wjZofJX0v4M",
      "title": "Transformers, explained",
      "author": "3Blue1Brown",
      "description": "A visual walkthrough of attention…",
      "thumbnail": "https://i.ytimg.com/vi/wjZofJX0v4M/hqdefault.jpg",
      "url": "https://www.youtube.com/watch?v=wjZofJX0v4M"
    }
  ],
  "usage": { "input_tokens": 1000, "output_tokens": 0, "cost_usd": 0.00065 }
}

Search real YouTube videos by title or description and get their links. query is required (max 300 characters), limit is 1–10 (default 5). Billed on input tokens only — no output tokens — with a 1,000-token floor per search.

A chatbot you design in the builder is served as a self-contained widget. Drop one script tag before </body> — the key stays on our servers, the bot id is public but only answers on the domains you allow.

<script src="https://cowork.fyi/api/public/dev/v1/widget.js?bot=bot_xxx" async></script>

Prefer your own interface? Call the same endpoint directly — no bearer token needed, because the bot id plus your domain allow-list is the credential.

curl https://cowork.fyi/api/public/dev/v1/chatbot \
  -H "Content-Type: application/json" \
  -d '{ "bot": "bot_xxx", "messages": [{ "role": "user", "content": "Do you ship to Canada?" }] }'

Both snippets are server-side only. Never place a Kove key in browser or mobile code.

const KOVE = "https://cowork.fyi/api/public/dev/v1";

async function kove(path, body) {
  const res = await fetch(KOVE + path, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.KOVE_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });
  const json = await res.json();
  if (!res.ok) throw new Error(json?.error?.message ?? `Kove ${res.status}`);
  return json;
}

const { output } = await kove("/chat", { input: "Hello" });

import os, requests

KOVE = "https://cowork.fyi/api/public/dev/v1"
headers = {"Authorization": f"Bearer {os.environ['KOVE_API_KEY']}"}

r = requests.post(f"{KOVE}/chat", headers=headers, json={"input": "Hello"})
r.raise_for_status()
print(r.json()["output"])

{ "error": { "type": "insufficient_funds", "message": "…" } }

• 400 invalid_request — malformed JSON or a missing required field.
• 401 unauthorized — missing, malformed, deleted, or revoked key.
• 402 insufficient_funds — balance is $0.00 or below.
• 502 server_error — upstream generation failure; safe to retry.
• 503 server_error — engine temporarily unavailable.

Kove Developer is strictly prepaid and denominated in US dollars. You add a custom amount (minimum $5, whole dollars) through Stripe; each call deducts its exact metered cost from the remaining balance, and every deduction is itemised on the Overview tab. There is no subscription, no auto-recharge, and no overdraft — calls simply stop at zero. Playground runs are billed at exactly the same rates as API calls.

Hand this to Cursor, Claude Code, Copilot, or any agent and it has everything needed to wire up the Kove API correctly: endpoints, payload shapes, pricing, error handling rules, and reference clients. If you intend to ask AI to add a chatbot to your site, build and publish it in the /dev/chatbot tab first, copy the bot ID there, and give the agent both the docs and that ID.