{/* GENERATED FROM Captcha-Sonic/captchasonic-csharp README.md — DO NOT EDIT. Run: bun run migrate:sdk-docs */}

[CaptchaSonic](https://captchasonic.com) CAPTCHA solving API용 공식 C# / .NET SDK입니다.

## 전송 방식

`Grpc.Net.Client`를 통해 네이티브 gRPC를 사용합니다. 이미지는 base64 오버헤드 없이 원시 바이너리로 전송됩니다.

## 설치

```bash
dotnet add package CaptchaSonic
```

## 빠른 시작

```csharp
using CaptchaSonic;

await using var client = new CaptchaSonicClient(new CaptchaSonicOptions
{
    ApiKey = "sonic_your_api_key"
});

double balance = await client.GetBalanceAsync();
Console.WriteLine($"Balance: ${balance:F4}");

byte[] tile = await File.ReadAllBytesAsync("tile.png");
var result = await client.SolvePopularCaptchaAsync(
    images: new[] { tile },
    question: "Select all traffic lights",
    questionType: "objectClassify"
);
Console.WriteLine(string.Join(", ", result.TypedSolution.Grid.Objects));
```

### 간단한 생성자

```csharp
await using var client = new CaptchaSonicClient("sonic_your_api_key");
```

---

## 설정

```csharp
var client = new CaptchaSonicClient(new CaptchaSonicOptions
{
    ApiKey      = "sonic_your_api_key",          // required, must start with "sonic_"
    Endpoint    = "https://api.captchasonic.com", // optional, default shown
    CallTimeout = TimeSpan.FromSeconds(30),       // optional, per-call gRPC deadline
});
```

클라이언트는 **스레드 안전**합니다. 인스턴스를 하나 만들어 애플리케이션 전체에서 재사용하세요.

---

## 이미지 솔버

### `SolvePopularCaptchaAsync()`

```csharp
await client.SolvePopularCaptchaAsync(
    images: new[] { tile },
    question: "Select all traffic lights",
    questionType: "objectClassify",   // "objectClassify" | "objectClick" | "objectDrag" | "grid"
    examples: null,                   // optional reference images
    screenshot: false,                // optional
    websiteUrl: "https://example.com", // optional, billing context
    websiteKey: null                  // optional, billing context
);
```

### `SolveRecaptchaV2Async()`

```csharp
await client.SolveRecaptchaV2Async(
    images: new[] { tile },
    question: "traffic lights",       // or "/m/015qff"
    questionType: "split_33",         // "split_33" | "33" | "44". Optional.
    websiteUrl: null,                 // optional
    websiteKey: null                  // optional
);
```

### `SolveGeetestAsync()`

```csharp
await client.SolveGeetestAsync(
    geetestType: "nine",              // "nine" | "click" | "slide" | "match" | "winlinze"
    question: "the bear",             // required for "nine" and "click"
    images: new[] { tile },           // required for "nine", "click", "slide"
    examples: null,                   // optional reference images
    image: null,                      // slice piece for "slide"
    gtv: 3,                           // Geetest version, default 3
    websiteUrl: null                  // optional
);
```

### `SolveOcrAsync()`

```csharp
await client.SolveOcrAsync(
    images: new[] { tile },
    module: "common",                 // "common" | "mtcaptcha" | "bls" | "morocco"
    websiteUrl: null                  // optional
);
// Returns: result.TypedSolution.Text.Texts[0]
```

### `SolveTikTokAsync()`

```csharp
await client.SolveTikTokAsync(
    type: "whirl",                    // "click" | "whirl" | "slide"
    question: "",                     // optional
    images: new[] { tile },
    examples: null,                   // required for "whirl" and "slide"
    websiteUrl: null                  // optional
);
```

### `SolveBinanceAsync()`

```csharp
await client.SolveBinanceAsync(
    type: "grid",                     // "grid" | "slide"
    question: "Select the bicycle",   // required for "grid"
    images: new[] { tile },
    examples: null,                   // optional
    websiteUrl: null                  // optional
);
```

### `SolveAwsWafAsync()`

```csharp
await client.SolveAwsWafAsync(
    images: new[] { tile },
    question: "grid:vehicles:cars",
    websiteUrl: null,                 // optional
    websiteKey: null                  // optional
);
```

### `SolveSlideImageAsync()`

```csharp
await client.SolveSlideImageAsync(images: new[] { background, piece });
// Returns: result.TypedSolution.Slide.X — pixel offset
```

---

## 토큰 자동화 메서드

이 메서드들은 작업을 제출한 뒤 토큰이 반환될 때까지 폴링합니다(최대 120초).

```csharp
await client.SolveTurnstileAsync(websiteUrl, websiteKey, proxy?);
await client.SolvePopularCaptchaTokenAsync(websiteUrl, websiteKey, proxy?);
await client.SolveRecaptchaV2TokenAsync(websiteUrl, websiteKey, proxy?);
await client.SolveRecaptchaV3TokenAsync(websiteUrl, websiteKey, proxy?);
await client.SolveCloudflareAsync(websiteUrl, websiteKey, proxy);  // proxy required
```

---

## 유틸리티 메서드

```csharp
double balance = await client.GetBalanceAsync();
var health     = await client.HealthCheckAsync();
var result     = await client.GetTaskResultAsync(taskId);
var response   = await client.CreateTaskAsync(task);
```

---

## 오류 처리

```csharp
try
{
    var result = await client.SolvePopularCaptchaAsync(images, question, questionType);
}
catch (InvalidApiKeyException)         { /* errorId=1 */ }
catch (InsufficientBalanceException)   { /* errorId=2 */ }
catch (DailyLimitExceededException)    { /* errorId=3 */ }
catch (MinuteLimitExceededException)   { /* errorId=4 */ }
catch (QuotaExceededException)         { /* errorId=5 */ }
catch (PlanExpiredException)           { /* errorId=6 */ }
catch (CaptchaSonicException)          { /* other errors */ }
```

`Unavailable`, `ResourceExhausted`, `DeadlineExceeded`가 발생하면 지수 백오프로 자동 재시도합니다.

---
