Skip to main content

AI Fabric Quick Start

Get from zero to a successful AI chat call in under 5 minutes.

Prerequisites​

  1. API key: Get one from the console
  2. Base URL: https://api.vagarylabs.com

Step 1: Your first chat call​

curl​

bash\ncurl -X POST https://api.vagarylabs.com/v1/llm/chat \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer vgk_YOUR_API_KEY\" \\\n -d '{\n \"messages\": [\n {\"role\": \"user\", \"content\": \"What is the capital of France?\"}\n ],\n \"model\": \"gpt-4o\"\n }'\n

TypeScript​

typescript\nimport { Client } from \"@vagary/shared-sdks\";\n\nconst client = new Client({\n baseUrl: \"https://api.vagarylabs.com\",\n headers: { Authorization: \"Bearer vgk_YOUR_API_KEY\" },\n});\n\nconst response = await client.default.llmChat({\n messages: [{ role: \"user\", content: \"What is the capital of France?\" }],\n model: \"gpt-4o\",\n});\n\nconsole.log(response.content);\n// => \"The capital of France is Paris.\"\n

Python​

python\nfrom clients.provider_gateway_client import Client\n\nclient = Client(\n base_url=\"https://api.vagarylabs.com\",\n headers={\"Authorization\": \"Bearer vgk_YOUR_API_KEY\"},\n)\n\nresponse = client.default.llm_chat(\n messages=[{\"role\": \"user\", \"content\": \"What is the capital of France?\"}],\n model=\"gpt-4o\",\n)\n\nprint(response.content)\n# => \"The capital of France is Paris.\"\n

Step 2: Understand the response​

Every response includes a usage object with billing details:

json\n{\n \"content\": \"The capital of France is Paris.\",\n \"usage\": {\n \"prompt_tokens\": 12,\n \"completion_tokens\": 6,\n \"provider_used\": \"openai\",\n \"cost_cents\": 0.00024\n }\n}\n

| Field | Description |\n|---|---|\n| prompt_tokens | Tokens in your input |\n| completion_tokens | Tokens in the response |\n| provider_used | Which AI provider served this request |\n| cost_cents | Cost in cents (billed to your org) |\n\n## Step 3: Try streaming

For real-time responses, add \"stream\": true:

bash\ncurl -X POST https://api.vagarylabs.com/v1/llm/chat \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer vgk_YOUR_API_KEY\" \\\n -d '{\n \"messages\": [\n {\"role\": \"user\", \"content\": \"Write a haiku about coding\"}\n ],\n \"model\": \"gpt-4o\",\n \"stream\": true\n }'\n

Step 4: Try embeddings​

Convert text to vectors for semantic search:

bash\ncurl -X POST https://api.vagarylabs.com/v1/embeddings \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer vgk_YOUR_API_KEY\" \\\n -d '{\n \"input\": \"The quick brown fox jumps over the lazy dog\",\n \"model\": \"text-embedding-3-small\"\n }'\n

Step 5: Set the language​

Control which language the model responds in:

curl -X POST https://api.vagarylabs.com/v1/llm/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer vgk_YOUR_API_KEY" \
  -d '{
    "messages": [
      {"role": "user", "content": "Tell me about Paris"}
    ],
    "model": "gpt-4o",
    "locale": "es-MX",
    "locale_mode": "force"
  }'
locale_modeBehavior
auto (default)"Respond in the language the user writes in" — respects input language
force"Always respond in {locale}" — overrides input language

Step 6: Handle errors​

All errors include an error_class for programmatic branching:

json\n{\n \"error\": \"rate_limited\",\n \"error_class\": \"rate_limit\",\n \"retryable\": true,\n \"retry_after\": 30\n}\n

See the error handling guide for the full table.

Next steps​

Troubleshooting​

"no provider configured (missing keys)"​

The gateway needs at least one provider key. Either:

  • Use the fleet key (pre-configured by your admin)
  • Set up BYOK (Bring Your Own Key) via the BYOK endpoints

"rate_limited"​

You've hit the rate limit. Check retry_after in the error response and retry after that many seconds.

"all_providers_failed"​

All AI providers are temporarily unavailable. The gateway will automatically retry — try your request again in a few seconds.