内容
代理构建（Cursor、Claude Code、CopCodex、Gemini CLI）
该附带 AI 编码代理直接读取的文档：
-ENTS.md` 快速入门、模式、注意事项和常用任务参考 `docs/llms-full.txt` 包含每个端点完整方法参考
支持 `AGENTS.md` 的代理aude Code、Cursor、GitHub Copilot、OpenAI Codex、Gemini CLI）会自动拾取它。对于其他工具，请在 `~/.nuget/packages/roxyapi.sdk/<version>/` 下指向恢复的软件包。
偏好 MCP？每个领域都有一个远程 MCP 服务器，位于 `https://roxyapi.com/mcp/{domain}`（可流式传输的 HTTP，无 stdio，无自托管）。Claude Code 设置的一行代码：
```bash
claude mcp add-json --scope user roxy-astrology \
'{"type":"http","url":"https://roxyapi.com/mcp/astrology","headers":{"X-API-Key":"YOUR_KEY"}}'
```
## 身份验证
在 [roxyapi.com/pricing](https://roxyapi.com/pricing) 获取您的 API 密钥，结账后立即交付。
```csharp
var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
```
永远不要在桌面、移动、浏览器或 Unity 客户端中公开您的 API 密钥。仅从您的服务器、API 或后端调用 Roxy。
对于高级用法（自定义 `HttpClient`、代理或您自己的中间件），使用 Kiota 请求适配器构建客户端：
```csharp
using Microsoft.Kiota.Http.HttpClientLibrary;
var adapter = new HttpClientRequestAdapter(authProvider, httpClient: yourHttpClient);
var roxy = new RoxyClient(adapter);
```
## 多语言响应
解释和编辑文本提供八种语言：中文（`zh）、英语（`en`）、土耳其语（`tr`）、德语（`de`）、西班牙语（`es`）、法语（`fr`）、印地语（`hi`）、葡萄牙语（`pt`）、俄语（`ru`）。通过查询配置在任何支持的端点传递 `Lang`：
```csharp
var card = await roxy.Tarot.Daily.PostAsync new() { Date = new Date(2026, 422) },
c => c.QueryParameters.Lang = "es");
```
支持：占星吠陀占星术、数秘学、塔罗生物节律、易经、水晶、天使数字。仅：梦境、位置。未翻译的字段会默认为英文。调用 `roxy.Languages.GetAsync()` 以获取实时列表。
每个端点在 4xx 或 5xx时都会抛出一个类型化的 `RoxyError`（继承ApiException`）。消息是人类可读的；通过 ` 进行程序化处理：
```csharp
using RoxyApi.Models;
try
{
var horoscope = await roxy.Astoroscope["aries"].Daily.GetAsync();
Console.Writeoroscope!.Overview);
}
catch (RoxyError e)
{
// e.Code 是稳定的；e.Message 可能会更改。eCode 是 HTTP 状态。
// 在 400 时，e.Issues 列出每个验证失败的字段。
Console.WriteLine($"{e.ResponseStatusCode} {e.Code}: {e.Message}");
}
```
| 状态码 | 代码 | 何时发生 |
|--------|------|------|
| 400 | `validation_error` | 缺少或无效的参数（参见 `Issues`） |
| 401 | `api_key_required` | 未提供 API 密钥 |
| 401 | `invalid_api_key` |格式无效或被篡| 401 | `subscription_not_found` | 密钥引用一个不存在的订阅 |
| 401 | `subscription_inactive` | 订阅已取消、过期或暂停 |
| 404 | `not | 资源未找到 |
| 429 | `rate_limit_ex | 每月配额已达到 |
| 500 | `internal_error` | 服务器错误 常见问题
### 如何发现字段？
每个响应都是一个完全类型化的对象，因此您的 IDE 会自动完成每个字段。没有未类型的字典可供。每个端点的完整响应 JSON（带有真实的生产数据）都在实时 [API 参考游乐场](https://roxyapi-reference) 上。您很少自己编写响应类型名称：var` 捕获结果，让 IntelliSense 显示形状（生成的（如 `SearchGetResponse_cities`）是内部管道）。
### 城市查找返回什么？
`roxy.Location.SearchCities`，一个列表，其中每个项目都有 `City`）、`Country`、`Province`、`Latitude`、`LongitudeTimezone`（IANA 字符串）、`UtcOffset`（小数Population`。
```csharp
var search = await roxy.Location.Search.GetAsync(c => c.QueryParameters.Q = "London, UK");
var city = search!.Cities![0];
Console.WriteLine($"{city.City}, {city.Country} at {city.Latitude}, {city.Longitude} ({city.Timezone}) 出生图表返回
`PlanetsHouses`、`Aspects`、`Ascendant`、`Midheaven`、`PartOfFort、`Patterns` 和 `Summary`。每个行星Name`、`Sign`、`Degree`、`House`、`IsRetrograde` 和 `Speed`。`Planets` 列表涵盖现代占星术中使用的完整集合（十个经典天体加上月球节点和关键点），因此预计超过十个条目。
```csharp
var chart = await roxy.Astrology.NatalChart.PostAsync(new()
{
Date = new Date(1990, 1, 15), Time = new Time(14, 30, 0),
Latitude = 40.7128, Longitude = -74.006, Timezone = new() { Double = -5 },
});
foreach (var planet in chart!.Planets!)
Console.WriteLine($"{planet.Name}: {planet.Sign} {planet.Degree:F2}（house {planet.House}）");
```
### 调用会返回错误对象还是抛出？
它们会抛出。成功时，调用会返回类型化的响应（可为空的引用，因此在处理错误后使用 `!` 或空检查）；在 4xx 或 5xx 时，会抛出 `RoxyError`。在 `try`/`catch (RoxyError e)` 中包装调用，并切换到 `e.Code`。
### 支持哪些 .NET 版本？
.NET 8 及更高版本，以及任何使用 `netstandard2.0` 的运行时：.NET Framework 4.6.1+、Unity、Xamarin、MAUI 和 Mono。建议语言版本 12 或更高版本，以使用这些示例中的集合表达式和目标类型 `new()` 语法。
## 要求和依赖项
- **.NET 8 或更高版本，或任何支持 `netstandard2.0` 的运行时**（.NET Framework 4.6.1+、Unity、Mono）。建议语言版本 12 或更高版本，以使用上述集合表达式和目标类型 `new()` 语法。
- **[`Microsoft.Kiota.Bundle`](https://www.nuget.org/packages/Microsoft.Kiota.Bundle)** 是唯一的运行时依赖项。它拉入由 Kiota HTTP、身份验证和序列化库（所有 MIT 许可，由 Microsoft 维护）驱动的生成的客户端。
类型化的客户端是从公共 OpenAPI 规范使用 [Kiota](https://learn/openapi/kiota/) 生成的，因此 SDK 与 API 和新端点保持同步。
## 链接
- [文档](https://roxyapi.com/docs)
- [API 参考](https://roxyapi.com/api-reference)
- [定价](https://roxyapi.com/pricing)
- [AI 代理的 MCP 设置](https://roxyapi.com/docs/mcp)
- [模板](https://roxyapi.com/starters)
- [TypeScript SDK](https://www.npmjs.com/package/@roxyapi/sdk) | [Python SDK](https://pypi.org/project/roxy-sdk/) | [PHP SDK](https://packagist.org/packages/roxyapi/sdk)
- [问题](https://github.com/RoxyAPI/sdk-dotnet/issues)
## 许可证
MIT
