How to Configure Base URL? Differences Between /v1, Root Domain, and /v1beta

Complete guide to configuring API.YI Base URL: /v1 for OpenAI, root domain for Claude, /v1beta for Gemini

Quick Answer

Remember this: OpenAI models need /v1, Claude uses root domain only, Gemini needs /v1beta. Incorrect Base URL is the most common integration issue.

Model Family	Base URL	SDK
GPT / DeepSeek / Llama / Qwen etc.	https://api.apiyi.com/v1	OpenAI SDK
Claude series	https://api.apiyi.com	Anthropic SDK
Gemini series	https://api.apiyi.com	Google GenAI SDK (set api_version: "v1beta")

Why Different Base URLs for Different Models?

This is determined by each vendor’s SDK implementation:

• OpenAI SDK: Appends resource paths after base_url, so /v1 must be included
• Anthropic SDK: Internally appends /v1/messages — adding /v1 yourself results in /v1/v1/messages (404 error)
• Google GenAI SDK: Uses /v1beta path, SDK handles concatenation automatically

Code Examples

OpenAI-Compatible Models (GPT / DeepSeek / Llama etc.)

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # Domain + /v1
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)

Claude Models (Anthropic SDK)

import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com"  # Root domain only, NO /v1
)

message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}]
)
print(message.content[0].text)

Gemini Models (Google GenAI SDK)

from google import genai

client = genai.Client(
    api_key="YOUR_API_KEY",
    http_options={"api_version": "v1beta", "base_url": "https://api.apiyi.com"}
)

response = client.models.generate_content(
    model="gemini-2.5-pro",
    contents="Hello!"
)
print(response.text)

Common mistake for Claude users: When using the official Anthropic SDK, Base URL should be https://api.apiyi.com only — do NOT add /v1. However, if you’re calling Claude through OpenAI SDK’s compatible mode, you DO need /v1.

Domain Node Selection

APIYI provides 4 domain nodes with identical features, differing in network routing and deployment architecture:

🌏 Global Direct (Recommended for Overseas)

vip.apiyi.com

Direct connection to backend, lowest latency. Recommended for all non-China-mainland customers.

🇨🇳 China Default (Recommended for Mainland)

api.apiyi.com

Optimized for China mainland network. Default for China mainland customers.

🏢 China Backup / Business

b.apiyi.com

Backup node and Business enterprise line. Use when primary node is unavailable.

⚡ Cloudflare CDN Global Acceleration

api-cf.apiyi.com

Cloudflare global CDN acceleration. For text-only API calls. Has a 100-second timeout limit.

Node	Domain	Recommended For	Notes
Global Direct	vip.apiyi.com	Non-China-mainland customers	Direct backend, lowest latency
China Default	api.apiyi.com	China mainland customers	Optimized domestic routing (default)
China Backup/Business	b.apiyi.com	Enterprise / backup	Backup + Business
Cloudflare CDN	api-cf.apiyi.com	Text-only calls	Global acceleration, 100s timeout

Cloudflare CDN Node Limitation: api-cf.apiyi.com is deployed on Cloudflare Workers, which has a maximum request timeout of 100 seconds. Therefore:

• ✅ Suitable for: Regular text chat, short text generation, and other fast-response calls
• ❌ Not suitable for: Complex long-text tasks exceeding 100 seconds
• ❌ Not suitable for: Nano Banana Pro and other image generation tasks
• ❌ Not suitable for: Video generation API calls

If your tasks may exceed 100 seconds, use vip.apiyi.com (overseas) or api.apiyi.com (China mainland) instead.

We recommend configuring a fallback node in your code for automatic switching to improve service availability.

Common Error Troubleshooting

Error	Possible Cause	Solution
404 Not Found	Missing /v1 in OpenAI SDK, or extra /v1 in Anthropic SDK	Verify path matches SDK specification
400 Bad Request	Gemini SDK path version mismatch	Confirm using /v1beta
Connection Timeout	Wrong domain node	Use api.apiyi.com in China, vip.apiyi.com overseas; CF-CDN node has 100s timeout limit
SSL Error	Missing https:// prefix	All nodes require HTTPS
Double Slash Error	Trailing / in base_url	Remove trailing slash

Full Configuration Reference

OpenAI-Compatible Models

Node	Base URL
Global Direct (Overseas)	https://vip.apiyi.com/v1
China Default (Mainland)	https://api.apiyi.com/v1
China Backup/Business	https://b.apiyi.com/v1
Cloudflare CDN (Text Only)	https://api-cf.apiyi.com/v1

Claude Models (Anthropic SDK)

Node	Base URL
Global Direct (Overseas)	https://vip.apiyi.com
China Default (Mainland)	https://api.apiyi.com
China Backup/Business	https://b.apiyi.com
Cloudflare CDN (Text Only)	https://api-cf.apiyi.com

Gemini Models

Node	Base URL
Global Direct (Overseas)	https://vip.apiyi.com
China Default (Mainland)	https://api.apiyi.com
China Backup/Business	https://b.apiyi.com
Cloudflare CDN (Text Only)	https://api-cf.apiyi.com

When using the Google GenAI SDK for Gemini, set base_url to the root domain and api_version: "v1beta" — the SDK will automatically construct the full path.