> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yelu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Best practices

> Build reliable, secure, observable, and cost-aware production applications on Yelu AI API.

Production AI integrations need conventional distributed-systems discipline plus model-specific validation. Use this checklist before exposing a Yelu-backed feature to users.

## Discover capabilities

Query [`GET /v1/models`](/en/api-reference/models) and keep model selection in configuration. A catalog entry means the key can route to the model; verify vision, tools, structured output, audio, and other capabilities with a contract test.

## Set explicit boundaries

* Set connect, read, and total deadlines for every request.
* Bound input bytes, message count, tool schema size, image dimensions, audio size, and output tokens.
* Limit tool-loop iterations and concurrent model calls per user.
* Use server-side cancellation when the caller disconnects.
* Reject unknown user-selected models unless they are in an allowlist built from the current catalog.

## Retry selectively

Retry `429` and temporary `5xx` responses with exponential backoff, jitter, and a small total retry budget. Do not retry invalid or unauthorized requests unchanged. See [Rate limits](/en/rate-limits).

<CodeGroup>
  ```bash Curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --connect-timeout 10 --max-time 90 \
    --retry 3 --retry-all-errors --retry-delay 1 \
    https://api.yelu.ai/v1/models \
    -H "Authorization: Bearer $YELU_API_KEY"
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const controller = new AbortController();
  const timeout = setTimeout(() => controller.abort(), 90_000);
  try {
    const response = await fetch('https://api.yelu.ai/v1/models', {
      headers: { Authorization: `Bearer ${process.env.YELU_API_KEY}` },
      signal: controller.signal,
    });
    if (!response.ok) throw new Error(await response.text());
    console.log(await response.json());
  } finally {
    clearTimeout(timeout);
  }
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import os
  import requests
  from requests.adapters import HTTPAdapter
  from urllib3.util.retry import Retry

  session = requests.Session()
  session.mount("https://", HTTPAdapter(max_retries=Retry(
      total=3,
      backoff_factor=0.5,
      status_forcelist=[429, 500, 502, 503, 504],
      allowed_methods=["GET"],
  )))
  response = session.get(
      "https://api.yelu.ai/v1/models",
      headers={"Authorization": f"Bearer {os.environ['YELU_API_KEY']}"},
      timeout=(10, 30),
  )
  response.raise_for_status()
  print(response.json())
  ```
</CodeGroup>

## Protect data and keys

* Keep Yelu keys in server-side secret storage and use one key per environment/workload.
* Redact authorization, prompts, tool arguments, files, and model output from default logs.
* Classify data before sending it to any AI model and enforce your retention and residency requirements.
* Treat model output, URL input, and function arguments as untrusted.
* Require deterministic authorization for every tool action.

## Make outputs dependable

* Use structured output for machine-consumed data and validate it locally.
* Use low randomness for extraction, classification, and workflow control.
* Check finish status before consuming output; `length` and content filtering can produce incomplete results.
* Maintain versioned evaluation cases for prompts, schemas, model changes, and fallback behavior.
* Make fallback models explicit because quality, safety, latency, and output shape can differ.

## Observe the system

Record enough metadata to debug without collecting unnecessary content:

| Signal      | Examples                                                              |
| ----------- | --------------------------------------------------------------------- |
| Request     | Endpoint, model, key/workload label, input size, stream flag          |
| Result      | Status, error type/code, finish reason, complete/partial state        |
| Performance | Queue time, time to first token, total latency, retry count           |
| Usage       | Input, output, cached, reasoning, image, or audio units when returned |
| Quality     | Schema validity, tool success, user feedback, evaluation score        |

## Control cost

* Choose the smallest model that passes your evaluation threshold.
* Trim conversation history and retrieve only relevant context.
* Cap output, image count, dimensions, and audio duration.
* Deduplicate safe, deterministic work at the application layer.
* Attribute usage with separate keys and dashboard monitoring.

<Warning>
  Never silently switch to a model with materially different safety or data-handling characteristics. Treat fallback as a product and compliance decision, not only a reliability mechanism.
</Warning>