AI API 接入完全指南：5 分钟上手

把 AI 能力集成到应用中？这个指南帮你从零开始，5 分钟发送第一个 API 请求。

第 1 步：注册获取 API Key

第 2 步：发送请求

DrAI 完全兼容 OpenAI 格式：

curl https://api.dr-ai.top/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-key" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello"}]}'

第 3 步：切换模型

改 model 参数：claude-opus-4 · deepseek-r1 · gemini-2.5-pro

第 4 步：流式输出

加 "stream":true 启用 SSE 流式输出。

SDK 支持

• Python: pip install openai → base_url="https://api.dr-ai.top/v1"
• JS/TS: npm install openai → 同设 baseURL
• LangChain: ChatOpenAI + 自定义 base_url

完整 Python SDK 示例

上面是最简调用。真实项目中你需要处理流式输出、错误重试、token 计费。以下是生产级代码模板：

from openai import OpenAI
import time

client = OpenAI(
    api_key="your-dr-ai-key",
    base_url="https://api.dr-ai.top/v1"
)

def chat(prompt, model="deepseek-r1", system=None, temperature=0.7):
    """带重试的生产级调用"""
    messages = []
    if system:
        messages.append({"role": "system", "content": system})
    messages.append({"role": "user", "content": prompt})

    for attempt in range(3):
        try:
            response = client.chat.completions.create(
                model=model,
                messages=messages,
                temperature=temperature,
                max_tokens=2000,
            )
            return {
                "content": response.choices[0].message.content,
                "tokens_in": response.usage.prompt_tokens,
                "tokens_out": response.usage.completion_tokens,
                "model": model,
            }
        except Exception as e:
            if attempt == 2:
                raise
            time.sleep(2 ** attempt)  # 指数退避

# 使用示例
result = chat(
    "用 Python 写一个二分查找",
    model="deepseek-r1",       # 性价比最高
    system="你是资深 Python 工程师，代码必须有注释和类型标注",
    temperature=0.2,           # 代码用低温度
)
print(result["content"])
print(f"\n消耗: {result['tokens_in']}+{result['tokens_out']} tokens")

流式输出实战

流式输出（SSE）让用户逐字看到回答，体验远好于等待完整响应。对于长文本生成（文章、代码）尤其重要：

# Python 流式输出
stream = client.chat.completions.create(
    model="gpt-5.6",
    messages=[{"role": "user", "content": "写一篇 1000 字的科技博客"}],
    stream=True,  # 开启流式
)

full_text = ""
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)  # 实时打印
        full_text += delta

print(f"\n\n完整长度: {len(full_text)} 字")

// JavaScript 流式输出（浏览器端）
const response = await fetch("https://api.dr-ai.top/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "gpt-5.6",
    messages: [{ role: "user", content: "讲个笑话" }],
    stream: true,
  }),
});

const reader = response.body.getReader();
const decoder = new TextDecoder();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const text = decoder.decode(value);
  // 解析 SSE 格式：data: {...}
  text.split("\n").forEach((line) => {
    if (line.startsWith("data: ") && line !== "data: [DONE]") {
      const json = JSON.parse(line.slice(6));
      const delta = json.choices[0]?.delta?.content;
      if (delta) document.body.innerHTML += delta;
    }
  });
}

多轮对话（带上下文）

真实聊天应用需要维护对话历史。每次请求把之前的对话都发过去：

conversation = [
    {"role": "system", "content": "你是友好的 AI 助手"}
]

def chat_turn(user_input):
    conversation.append({"role": "user", "content": user_input})

    response = client.chat.completions.create(
        model="claude-opus-4",
        messages=conversation,  # 发送完整历史
    )

    reply = response.choices[0].message.content
    conversation.append({"role": "assistant", "content": reply})
    return reply

# 模拟对话
print(chat_turn("我叫小明"))        # 你好小明！
print(chat_turn("我叫什么？"))       # 你叫小明（记住上文）

注意：对话越长，token 消耗越大。建议超过 10 轮时做摘要压缩，或设置 max_tokens 限制。

Function Calling（工具调用）

2026 年最重要的 API 能力。让 AI 能调用你的函数——查数据库、调 API、操作文件：

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "查询某城市天气",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "城市名"}
            },
            "required": ["city"]
        }
    }
}]

response = client.chat.completions.create(
    model="gpt-5.6",
    messages=[{"role": "user", "content": "北京天气怎么样？"}],
    tools=tools,
)

# AI 返回要调用的函数
tool_call = response.choices[0].message.tool_calls[0]
import json
args = json.loads(tool_call.function.arguments)
print(f"AI 想调用 get_weather({args})")
# → AI 想调用 get_weather({'city': '北京'})

# 你执行函数，把结果返回给 AI
weather = get_weather(args["city"])  # 你的实现
conversation = [
    {"role": "user", "content": "北京天气怎么样？"},
    response.choices[0].message,
    {"role": "tool", "tool_call_id": tool_call.id, "content": weather}
]
final = client.chat.completions.create(model="gpt-5.6", messages=conversation)
print(final.choices[0].message.content)
# → "北京今天晴，25度..."

各语言 SDK 速查

LangChain 集成

LangChain 是最流行的 LLM 应用框架。DrAI 完全兼容：

from langchain_openai import ChatOpenAI
from langchain.prompts import ChatPromptTemplate

llm = ChatOpenAI(
    model="deepseek-r1",
    api_key="your-key",
    base_url="https://api.dr-ai.top/v1",
    temperature=0.7,
)

prompt = ChatPromptTemplate.from_messages([
    ("system", "你是{role}，用{style}的风格回答"),
    ("user", "{question}")
])

chain = prompt | llm
response = chain.invoke({
    "role": "资深美食家",
    "style": "幽默",
    "question": "推荐一道家常菜"
})
print(response.content)

常见错误与解决方案

成本控制技巧

1. 选对模型

不是所有任务都需要 GPT-5。简单任务用 DeepSeek R1，成本降 95%。DrAI 的 /v1/models 接口可查看实时价格。

2. 缓存重复请求

相同输入缓存结果。Redis 缓存 24 小时，能省 30-50% 成本（很多用户问同样的问题）。

3. 设置 max_tokens

不限制的话 AI 可能写很长的废话。按场景设：max_tokens=500（摘要）、2000（文章）、4000（代码）。

4. Prompt 精简

System prompt 太长每次都在烧钱。精简 system prompt 到 200 字以内，高频内容放到 Few-shot 示例里。

5. 监控用量

DrAI 后台有实时用量看板。设置预算告警，超出自动暂停。建议按项目/用户分 Key 管理。

安全性最佳实践

• 永远不要把 Key 放前端代码：浏览器端代码人人可见。用后端代理。
• 用环境变量：.env 文件 + python-dotenv，不要硬编码。
• 设置 Key 权限：DrAI 支持按 Key 设置额度上限和可用模型。
• 过滤用户输入：防止 Prompt 注入（用户输入构造恶意指令）。
• 日志脱敏：记录请求时去掉用户隐私数据。
• HTTPS 强制：所有 API 调用走 HTTPS，DrAI 默认支持。

部署检查清单

上线前确认以下事项：

1. ✅ API Key 存在环境变量，不在代码仓库里
2. ✅ 实现了错误重试（至少 3 次，指数退避）
3. ✅ 设置了 timeout（建议 60-120 秒）
4. ✅ 配置了 max_tokens 防止超长输出
5. ✅ 流式输出已实现（如果面向终端用户）
6. ✅ 用量监控和预算告警已配置
7. ✅ 敏感词过滤（如果面向公众）
8. ✅ 压力测试通过（预计 QPS 的 3 倍）

嵌入模型与向量搜索

除了聊天补全，DrAI 还提供 Embedding API——把文本转成向量，用于语义搜索、推荐、分类。这是 RAG（检索增强生成）的基础：

# 生成文本向量
response = client.embeddings.create(
    model="text-embedding-3-large",
    input=["机器学习入门", "如何训练神经网络"]
)
vectors = [d.embedding for d in response.data]
# 每个向量 1536 维，相似度用余弦计算

# 语义搜索（配合向量数据库如 Pinecone/Milvus）
import numpy as np

def search(query, docs, doc_vectors, top_k=3):
    # 把查询转成向量
    q_vec = client.embeddings.create(
        model="text-embedding-3-large", input=query
    ).data[0].embedding

    # 计算余弦相似度
    sims = []
    for doc, vec in zip(docs, doc_vectors):
        sim = np.dot(q_vec, vec) / (np.linalg.norm(q_vec) * np.linalg.norm(vec))
        sims.append((doc, sim))

    # 返回最相似的 top_k
    return sorted(sims, key=lambda x: -x[1])[:top_k]

results = search("深度学习优化器", docs, doc_vectors)
for doc, score in results:
    print(f"{score:.2f}: {doc}")

图像理解（Vision API）

GPT-5.6 和 Gemini 2.5 Pro 支持图像输入。识别图表、读文档、分析 UI：

response = client.chat.completions.create(
    model="gpt-5.6",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "这张图是什么图表？提取数据。"},
            {"type": "image_url", "image_url": {
                "url": "data:image/png;base64,{base64编码的图片}"
            }}
        ]
    }]
)
print(response.choices[0].message.content)
# → "这是一张柱状图，展示了 2024-2026 年各季度营收..."

批处理 API（省 50%）

非实时任务（数据标注、批量生成）用 Batch API，价格半价，24 小时内返回：

# 1. 准备 batch 请求文件（JSONL）
{"custom_id": "req-1", "method": "POST", "url": "/v1/chat/completions",
 "body": {"model": "deepseek-r1", "messages": [{"role": "user", "content": "总结：..."}]}}
{"custom_id": "req-2", "method": "POST", "url": "/v1/chat/completions",
 "body": {"model": "deepseek-r1", "messages": [{"role": "user", "content": "总结：..."}]}}

# 2. 上传并创建 batch
batch = client.batches.create(
    input_file_id=file.id,
    endpoint="/v1/chat/completions",
    completion_window="24h"
)
# 3. 等待完成后下载结果（成本 -50%）

下一步

• 阅读 Prompt 工程指南 提升输出质量
• 学习 成本优化策略 降低 API 费用
• 了解 企业部署方案 用于生产环境

Error Handling Patterns

Robust error handling is the difference between a production-grade AI integration and one that fails silently under load. When working with LLM APIs, errors come from multiple sources: network failures, rate limits, model timeouts, invalid responses, and content filter triggers. A comprehensive error handling strategy addresses each category.

Exponential Backoff with Jitter

Rate limit errors (HTTP 429) are the most common transient failure when calling AI APIs. The standard remedy is exponential backoff — waiting progressively longer between retries. However, naive exponential backoff causes thundering herd problems when multiple clients retry simultaneously. Adding random jitter (a random delay component) spreads retries across time, dramatically improving success rates. The recommended pattern starts with a 1-second delay, doubles on each retry, adds 0-500ms of jitter, and caps at 60 seconds. Most production systems implement 3-5 retries before falling back to an alternative model or returning an error to the user.

Circuit Breaker Pattern

When an API endpoint experiences sustained failures, continuing to send requests wastes resources and can worsen the outage. The circuit breaker pattern monitors failure rates and temporarily stops sending traffic when failures exceed a threshold. A typical configuration opens the circuit after 5 consecutive failures, holds it open for 30 seconds, then allows a single test request (half-open state). If the test succeeds, the circuit closes and normal traffic resumes. If it fails, the circuit reopens for another cooldown period. This pattern prevents cascading failures and gives the upstream service time to recover.

Fallback Chains

Production AI systems should never depend on a single model or provider. A fallback chain defines an ordered list of models to try when the primary fails. A common chain is: GPT-5.6 → Claude Opus 4 → DeepSeek V3. If the primary model times out or returns an error, the system automatically retries with the next model in the chain. The key consideration is that fallback models should accept similar prompts — sticking to OpenAI-compatible APIs simplifies this. Monitoring which fallback models are activated most frequently provides early warning of provider instability.

Response Validation

AI models sometimes return malformed responses — incomplete JSON, truncated output, or unexpected content types. Every API response should be validated before use. For structured output requests (JSON mode), validate against a JSON schema before processing. For text responses, check minimum length, presence of expected sections, and absence of refusal markers. Implementing a validation layer catches model hallucinations and formatting errors before they propagate into your application logic. When validation fails, retrying with a more explicit prompt (adding format instructions or examples) often resolves the issue.

Streaming Implementation Guide

Streaming responses transforms user experience by delivering content incrementally rather than waiting for the complete response. For chat applications, streaming reduces time-to-first-token from 2-5 seconds to under 500ms, creating the perception of real-time conversation.

Server-Sent Events (SSE) Pattern

The standard streaming protocol for AI APIs is Server-Sent Events. The client opens a connection, and the server pushes data chunks as the model generates them. Each chunk contains a delta — the new tokens since the last chunk. The client assembles these deltas into the complete response. SSE connections are one-way (server to client), which is sufficient for streaming text generation. For bidirectional communication (e.g., voice assistants), WebSocket connections are more appropriate.

Handling Stream Interruptions

Network instability can interrupt streaming connections mid-response. Your implementation must handle partial responses gracefully. The recommended approach is to accumulate received tokens in a buffer, and if the connection drops, attempt to resume generation from the last received position using the accumulated context. Some APIs support resumption tokens for this purpose. If resumption is not available, retry the complete request — but inform the user that a new response is being generated to avoid confusion from duplicated content.

Backpressure Management

When a model generates tokens faster than the client can process them (e.g., the client is rendering complex markdown), backpressure builds up. Without management, this leads to unbounded memory consumption on the server. Implement flow control by pausing the upstream model stream when the client buffer exceeds a threshold (typically 4-8KB of unprocessed tokens). Resume the stream when the buffer drains below a low-water mark. This pattern, known as "watermarking," ensures stable memory usage regardless of client processing speed.

Stream Processing Pipeline

For applications that post-process model output (e.g., syntax highlighting, content filtering, translation), a stream processing pipeline handles each chunk as it arrives. The pipeline consists of stages: raw token accumulation, partial content detection, processing (filtering, transformation), and output buffering. The challenge is that processing stages like syntax highlighting require complete tokens — you cannot highlight half a keyword. The solution is a sliding window buffer that processes complete tokens immediately while holding incomplete tokens until the next chunk arrives.

Rate Limit Best Practices

Rate limits are the primary mechanism API providers use to ensure fair resource allocation. Understanding and optimizing for rate limits is critical for high-volume applications.

Understanding Limit Types

AI API providers typically enforce two types of rate limits: requests per minute (RPM) and tokens per minute (TPM). RPM limits constrain how many API calls you can make, while TPM limits constrain the total token volume (input plus output). For applications that send long prompts with short responses, TPM is rarely the bottleneck. For applications with short prompts but long responses (content generation), TPM limits are the primary constraint. Enterprise tiers often have separate concurrent request limits, restricting how many simultaneous in-flight requests are allowed.

Request Batching

When processing multiple independent queries, batching reduces RPM consumption. The OpenAI Batch API allows submitting up to 50,000 requests in a single batch, processed within 24 hours at a 50% discount. For near-real-time needs, the Batch API with a 1-hour completion target provides a good balance between cost savings and latency. Within individual requests, combining multiple questions into a single prompt (when they are related) reduces total API calls. However, avoid cramming unrelated queries into one request, as this degrades response quality and increases token usage.

Queue-Based Request Management

For applications with bursty traffic patterns, a request queue smooths consumption and prevents rate limit violations. Implement a token bucket or leaky bucket algorithm that tracks both RPM and TPM consumption. When a request arrives, the queue checks available capacity. If sufficient capacity exists, the request proceeds immediately. If not, the request waits in a priority-ordered queue. This approach ensures consistent throughput without exceeding limits, and it provides a natural mechanism for request prioritization (e.g., premium users get queue priority).

Proactive Limit Monitoring

All major API providers return rate limit headers with each response: remaining requests, remaining tokens, and reset timestamps. Monitoring these headers allows your application to anticipate limits before hitting them. When remaining capacity drops below 20%, the system can proactively throttle non-critical requests or redirect traffic to alternative providers. Building a dashboard that visualizes rate limit consumption in real-time helps operators understand usage patterns and make informed decisions about tier upgrades.

Security Checklist for AI API Integration

Security is paramount when integrating AI APIs into production systems. The following checklist covers the essential security controls every AI-powered application should implement.

API Key Management

Never hardcode API keys in source code, configuration files, or client-side JavaScript. Store keys in a secure secrets manager (AWS Secrets Manager, HashiCorp Vault, Doppler) and retrieve them at application startup. Rotate keys regularly — at minimum every 90 days — and maintain separate keys for development, staging, and production environments. Implement key scanning in your CI/CD pipeline to detect accidentally committed keys. Use IP allowlisting where available to restrict key usage to known server IPs.

Input Sanitization

All user-provided text that becomes part of an LLM prompt must be sanitized. The primary risks are prompt injection attacks, where malicious input attempts to override system instructions, and data exfiltration, where input contains instructions to reveal system prompts or API keys. Implement input filtering to detect and block common injection patterns ("ignore previous instructions", "reveal your system prompt"). Use structured prompt templates that clearly separate system instructions from user input using delimiters. For high-security applications, consider running a secondary model to evaluate user input for injection attempts before forwarding to the primary model.

Output Filtering and Validation

Model output should never be trusted blindly. Implement output validation layers that check for: personally identifiable information (PII) leakage, where the model might reveal training data; harmful content generation, including hate speech or dangerous instructions; and format compliance for structured outputs. Use regex patterns and NER (Named Entity Recognition) models to detect and redact PII in responses. For applications exposed to end users, implement content moderation filters that block responses containing prohibited content categories.

Rate Limiting and Abuse Prevention

Apply rate limiting at the application level, not just the API level. Per-user rate limits prevent individual users from consuming disproportionate resources. Implement progressive rate limiting: warn users at 80% of their limit, throttle at 100%, and temporarily block at 150%. For anonymous access, use IP-based rate limiting with CAPTCHA challenges for suspicious traffic patterns. Monitor for coordinated abuse — multiple IPs making similar requests in synchronized patterns — and implement automatic IP blocking for detected botnets.

Audit Logging

Maintain comprehensive audit logs of all AI API interactions. Each log entry should record: timestamp, user ID (if applicable), model used, prompt hash (not the full prompt, for privacy), response hash, token counts, latency, and success/failure status. These logs serve multiple purposes: debugging production issues, monitoring for abuse patterns, complying with regulatory requirements, and calculating cost attribution. Store logs in an append-only system with retention policies aligned to your compliance requirements — typically 90 days for operational logs and 7 years for regulated industries.

Data Privacy and Compliance

Understand the data processing policies of your AI API provider. Some providers retain prompts for model training; others offer zero-retention agreements for enterprise customers. For applications handling GDPR-regulated data, ensure your provider signs a Data Processing Agreement (DPA). For HIPAA-regulated healthcare data, use providers with signed Business Associate Agreements (BAAs). Implement data minimization — only send the minimum necessary information to the API. For example, replace actual names with tokens before sending text to the model, then re-substitute names in the response. This technique, called pseudonymization, reduces privacy risk while maintaining functionality.