Home Getting started Build with the Vinci API using practical patterns

Build with the Vinci API using practical patterns

Last updated on Aug 03, 2026

The Vinci API is OpenAI-compatible and credit-based. Here are patterns that help you ship faster and avoid common pitfalls when building applications powered by Vinci.

  1. Use streaming for better UX. Set "stream": true in your request to receive Server-Sent Events of chunks as they arrive, rather than waiting for the full response. Stream the chunks to your frontend for real-time display.

  2. Handle tool calling for agentic flows. Send a tools array with your request to enable function calling. Vinci returns tool_calls in the response; your code executes them and sends results back. Multi-turn tool use is supported—send prior calls and results in the messages array.

  3. Understand the model routing. Pin a class with "model": "mezzo", "model": "forte", or "model": "fortissimo", or use "model": "auto" to follow the class on the account. The API default is auto, and the account default is Forte. Mezzo is fast and light for everyday chat; for code and file tasks, Forte works best. Every class accepts a 1,000,000-token context window.

    Published API pricing per 1 million tokens:

    Class Input Output
    Vinci Mezzo $0.10 $0.21
    Vinci Forte (default) $1.07 $3.45
    Vinci Fortissimo $3.45 $17.25

    Mezzo cached input is $0.02 per 1 million tokens.

  4. Respect rate limits and errors. HTTP 429 (rate_limit_error) means temporary busy-time limits, not a billing problem—wait briefly and retry. HTTP 402 (budget_exhausted) means credits are exhausted. Implement exponential backoff for 429 and alert users for 402.

  5. Monitor usage on the Platform. Issue scoped API keys on platform.getsimpledirect.com. The inference scope covers /chat/completions calls. Track usage on the Platform Usage page to budget and set alerts via webhooks.

  6. Remember: no data retention by default. Prompts and completions are not logged or stored—only counts and metadata are recorded for billing. ZDR is automatic; opt-in features that do store data are clearly marked.