# Integration guide — Y-API

> Point base_url at Y-API and leave the rest of your code unchanged. The examples below run as copied, and all 15 models share the same pattern.

This is the markdown representation of https://y-api.bestvirtualgoods.com/docs. Generated by `scripts/generate-seo-assets.mjs` from the same copy the page renders — do not edit by hand.

## Basic configuration

Replace these three items in any OpenAI-compatible SDK. Get the api_key from the "API Keys" page in the console; set model to any ID from "Available models".

- `base_url`: https://api.y-api.bestvirtualgoods.com/v1
- `api_key`: sk-... (create in the console)
- `model`: deepseek/deepseek-v4-flash

## Make your first request

All three snippets are equivalent — copy whichever you already use.

### cURL

```bash
curl https://api.y-api.bestvirtualgoods.com/v1/chat/completions \
  -H "Authorization: Bearer $YAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek/deepseek-v4-flash",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

### Python (openai SDK)

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.y-api.bestvirtualgoods.com/v1",
    api_key=os.environ["YAPI_KEY"],  # key created in the console
)

response = client.chat.completions.create(
    model="deepseek/deepseek-v4-flash",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)
```

### Node.js (openai SDK)

```javascript
import OpenAI from 'openai'

const client = new OpenAI({
  baseURL: 'https://api.y-api.bestvirtualgoods.com/v1',
  apiKey: process.env.YAPI_KEY, // key created in the console
})

const response = await client.chat.completions.create({
  model: 'deepseek/deepseek-v4-flash',
  messages: [{ role: 'user', content: 'Hello!' }],
})
console.log(response.choices[0].message.content)
```

## Streaming

Add the stream parameter — chunks come back in the same SSE format as OpenAI, so clients need no special handling.

```python
stream = client.chat.completions.create(
    model="deepseek/deepseek-v4-flash",
    messages=[{"role": "user", "content": "Hello!"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")
```

## Switching models

All models share the same base_url and the same key — switching only means changing the model field. The full catalog is on the models page.

```python
# cheap, good for high-frequency and batch tasks
client.chat.completions.create(model="deepseek/deepseek-v4-flash", messages=msgs)

# stronger, good for complex reasoning
client.chat.completions.create(model="deepseek/deepseek-v4-flash", messages=msgs)
```

## Error handling

Two errors are the most common, and both leave a record in the console request log.

| Status | Meaning | What to do |
| --- | --- | --- |
| 401 | The key is invalid or has been revoked. | Check the key still exists on the "API Keys" page in the console, or create a new one. |
| 403 | Account credit is exhausted. Not 429 — and the message comes back in Chinese, which is why searching for it in English finds nothing. | Top up at https://y-api.bestvirtualgoods.com/app/billing — it recovers immediately, keys stay valid, no code changes needed. |

Do not read the cause off the status code: 5 of the 8 codes this gateway returns mean something other than what the number says, and the official SDKs silently retry 2 of those twice before your program ever sees them. The error reference lists every one of them with the message it actually returns.

## Machine-readable definitions

Writing an agent, or generating a client? The machine-readable OpenAPI 3.1 spec covers the three endpoints that exist here, every request and response field, and which failures the SDKs retry on their own.

The catalog is published as JSON too, and reading it needs no key: every model ID, its vendor, and both the credit price and the cash price. The gateway's own GET /v1/models endpoint does require one — this file is the anonymous equivalent, current as of the last build.

## Links

- HTML version of this page: https://y-api.bestvirtualgoods.com/docs
- Site index for agents: https://y-api.bestvirtualgoods.com/llms.txt
- Full reference (single file): https://y-api.bestvirtualgoods.com/llms-full.txt
- OpenAPI 3.1 spec: https://y-api.bestvirtualgoods.com/openapi.json
- Model catalog (JSON, no key needed): https://y-api.bestvirtualgoods.com/models.json
- API base URL: `https://api.y-api.bestvirtualgoods.com/v1`
- Contact: support@bestvirtualgoods.com
- Every error code, measured: https://y-api.bestvirtualgoods.com/docs/errors
- Model catalog: https://y-api.bestvirtualgoods.com/models
- Pricing (markdown): https://y-api.bestvirtualgoods.com/pricing.md
- Service status: https://y-api.bestvirtualgoods.com/status