Skip to main content

​
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 FamilyBase URLSDK
GPT / DeepSeek / Llama / Qwen etc.https://api.apiyi.com/v1OpenAI SDK
Claude serieshttps://api.apiyi.comAnthropic SDK
Gemini serieshttps://api.apiyi.comGoogle 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.comDirect connection to backend, lowest latency. Recommended for all non-China-mainland customers.

🇨🇳 China Default (Recommended for Mainland)

api.apiyi.comOptimized for China mainland network. Default for China mainland customers.

🏢 China Backup / Business

b.apiyi.comBackup node and Business enterprise line. Use when primary node is unavailable.

⚡ Cloudflare CDN Global Acceleration

api-cf.apiyi.comCloudflare global CDN acceleration. For text-only API calls. Has a 100-second timeout limit.
NodeDomainRecommended ForNotes
Global Directvip.apiyi.comNon-China-mainland customersDirect backend, lowest latency
China Defaultapi.apiyi.comChina mainland customersOptimized domestic routing (default)
China Backup/Businessb.apiyi.comEnterprise / backupBackup + Business
Cloudflare CDNapi-cf.apiyi.comText-only callsGlobal 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

ErrorPossible CauseSolution
404 Not FoundMissing /v1 in OpenAI SDK, or extra /v1 in Anthropic SDKVerify path matches SDK specification
400 Bad RequestGemini SDK path version mismatchConfirm using /v1beta
Connection TimeoutWrong domain nodeUse api.apiyi.com in China, vip.apiyi.com overseas; CF-CDN node has 100s timeout limit
SSL ErrorMissing https:// prefixAll nodes require HTTPS
Double Slash ErrorTrailing / in base_urlRemove trailing slash

​
Full Configuration Reference

​
OpenAI-Compatible Models

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

​
Claude Models (Anthropic SDK)

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

​
Gemini Models

NodeBase URL
Global Direct (Overseas)https://vip.apiyi.com
China Default (Mainland)https://api.apiyi.com
China Backup/Businesshttps://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.