# API v2 créditos, facturación y uso > Lea su saldo compartido de GenderAPI y comprenda los costos de crédito v2, las incógnitas facturables, los reembolsos, los saldos negativos y los tiempos de reinicio de la prueba de IP. Canonical HTML: https://www.genderapi.io/es/docs/v2/credits-and-usage Last reviewed: 2026-09-25 ## Créditos, resultados desconocidos y uso Una predicción completa con gender: null cuesta créditos según el modo seleccionado. La validación del teléfono cuesta 1 crédito incluso cuando valid: false. Los errores de validación de entrada antes de la facturación no cuestan créditos. Las predicciones fallidas no cuestan créditos después de un reembolso confirmado. Un saldo inicial positivo es suficiente para comenzar una sola solicitud o un lote. La deducción final puede hacer que el saldo sea negativo. Por ejemplo, comenzar con 1 crédito y usar una operación de IA que cueste 2 créditos deja un saldo de -1. Un saldo cero o negativo impide nuevas operaciones que cuesten créditos. Los reembolsos siguen siendo posibles. Verifique meta.usage.billing_status. El valor not_charged significa que no se dedujeron créditos y charged_credits: 0. El valor confirmed significa que se conoce el coste final. El valor unconfirmed significa que charged_credits es null y es necesario verificar el resultado de facturación. remaining_credits puede ser negativo o null si no está disponible. Este saldo se registra cuando se completa la operación y puede cambiar cuando se ejecutan otras solicitudes simultáneamente. OBTENER /uso es gratuito. Devuelve remaining_credits y expires_at. Para la prueba de IP, también devuelve resets_at, limit y period_seconds. El límite de prueba es de 10 créditos y el período es de 86400 segundos. Estos campos solo de prueba son null para cuentas de clave API. resets_at es el tiempo de reinicio de la prueba, no la fecha de vencimiento de la suscripción. V1 y v2 utilizan el mismo saldo de crédito. Las actualizaciones de saldo simultáneas de v1 y v2 pueden entrar en conflicto. No asuma que se garantiza que la facturación se realizará exactamente una vez en ambas versiones. ```json { "data": { "remaining_credits": 9, "expires_at": "2026-09-26T12:00:00.000Z", "resets_at": "2026-09-26T12:00:00.000Z", "limit": 10, "period_seconds": 86400 }, "meta": { "request_id": "11111111-1111-4111-8111-111111111111", "duration_ms": 12, "access": { "mode": "ip_trial", "reason": "api_key_missing" }, "usage": { "charged_credits": 0, "remaining_credits": 9, "billing_status": "not_charged", "resets_at": "2026-09-26T12:00:00.000Z", "limit": 10, "period_seconds": 86400 } } } ``` ## Consultar el saldo actual GET /api/v2/usage es gratuito y requiere autenticación Bearer, sin parámetros de consulta. Al omitir una clave se lee la asignación de prueba actual IP. Ejecute estos ejemplos en su servidor. Configure GENDERAPI_API_KEY en el entorno de proceso con su clave API existente. Confirme que meta.access.mode es api_key: una clave no reconocida puede recurrir a la prueba IP. Esta lectura de saldo no cuesta créditos. Todavía cuenta para los límites de tasa de solicitud. Las respuestas HTTP 4xx y 5xx JSON conservan el cuerpo del error y devuelven un estado de salida distinto de cero. Verifique code, action y meta.usage.billing_status antes de volver a intentarlo. **cURL** cURL 7.76+ en un shell POSIX. Ejecuta en tu terminal. ```bash curl --silent --show-error --fail-with-body --max-time 30 \ --request GET 'https://api.genderapi.io/api/v2/usage' \ --header "Authorization: Bearer ${GENDERAPI_API_KEY:?Set GENDERAPI_API_KEY}" ``` **JavaScript / Node.js** Node.js 22+; búsqueda incorporada. Guarde como example.mjs y ejecute node example.mjs. ```javascript // Server-side Node.js. Save as example.mjs. const apiKey = process.env.GENDERAPI_API_KEY; if (!apiKey) throw new Error("Set GENDERAPI_API_KEY"); const response = await fetch("https://api.genderapi.io/api/v2/usage", { method: "GET", headers: { Authorization: `Bearer ${apiKey}`, }, signal: AbortSignal.timeout(30_000), redirect: "error", }); const raw = await response.text(); if (!(response.headers.get("content-type") ?? "").includes("json")) { throw new Error(`HTTP ${response.status}: expected JSON; request ID ${response.headers.get("x-request-id")}`); } const result = JSON.parse(raw); // Also accepts application/problem+json. if (!response.ok) { console.error(`HTTP ${response.status}`, result); process.exitCode = 1; // A retry is a new operation; inspect billing first. } else { console.log(JSON.stringify(result, null, 2)); // For batches, inspect every item: HTTP 200 may contain item errors. } ``` **Python** Python 3.10+; biblioteca estándar. Guarde como example.py y ejecute python3 example.py. ```python import json import os import sys import urllib.error import urllib.request api_key = os.environ.get("GENDERAPI_API_KEY") if not api_key: raise RuntimeError("Set GENDERAPI_API_KEY") class NoRedirect(urllib.request.HTTPRedirectHandler): def redirect_request(self, req, fp, code, msg, headers, newurl): return None request = urllib.request.Request( "https://api.genderapi.io/api/v2/usage", method="GET", headers={ "Authorization": "Bearer " + api_key, }, ) opener = urllib.request.build_opener(NoRedirect()) try: response = opener.open(request, timeout=30) except urllib.error.HTTPError as error: response = error # Keep the Problem Details body on non-2xx responses. with response: status = response.status raw = response.read().decode("utf-8") if "json" not in response.headers.get("Content-Type", ""): raise RuntimeError(f"HTTP {status}: expected a JSON response") result = json.loads(raw) print(json.dumps(result, indent=2), file=sys.stderr if status >= 300 else sys.stdout) if not 200 <= status < 300: sys.exit(1) # Inspect code, action and billing before retrying. # For batches, inspect every item even when HTTP status is 200. ``` **PHP** PHP 8+ con la extensión cURL. Guarde como example.php y ejecute php example.php. ```php 'GET', CURLOPT_RETURNTRANSFER => true, CURLOPT_FOLLOWLOCATION => false, CURLOPT_TIMEOUT => 30, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . $apiKey, ], ]); $raw = curl_exec($ch); if ($raw === false) { throw new RuntimeException(curl_error($ch)); } $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); $contentType = curl_getinfo($ch, CURLINFO_CONTENT_TYPE) ?: ''; curl_close($ch); if (strpos($contentType, 'json') === false) { throw new RuntimeException("HTTP $status: expected a JSON response"); } $result = json_decode($raw, true, 512, JSON_THROW_ON_ERROR); $output = json_encode($result, JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR) . PHP_EOL; if ($status < 200 || $status >= 300) { fwrite(STDERR, $output); // Preserve the Problem Details body. exit(1); } echo $output; // For batches, inspect every item; HTTP 200 can contain item errors. ``` **Java** Java 17+; cliente estándar HTTP. Guarde como GenderApiExample.java y ejecute java GenderApiExample.java. ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.nio.charset.StandardCharsets; import java.time.Duration; public class GenderApiExample { private static String requiredEnv(String name) { String value = System.getenv(name); if (value == null || value.isBlank()) throw new IllegalStateException("Set " + name); return value; } public static void main(String[] args) throws Exception { String apiKey = requiredEnv("GENDERAPI_API_KEY"); HttpClient client = HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(10)) .followRedirects(HttpClient.Redirect.NEVER) .build(); HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.genderapi.io/api/v2/usage")) .timeout(Duration.ofSeconds(30)) .header("Authorization", "Bearer " + apiKey) .GET() .build(); HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8)); if (!response.headers().firstValue("content-type").orElse("").contains("json")) { throw new IllegalStateException("HTTP " + response.statusCode() + ": expected JSON"); } // JSON text; parse with your application's JSON library when integrating. if (response.statusCode() < 200 || response.statusCode() >= 300) { System.err.println(response.body()); // Includes Problem Details. System.exit(1); } System.out.println(response.body()); // For batches, inspect each item's data or error, including on HTTP 200. } } ``` **C# / .NET** Aplicación de consola .NET 8+. Úselo como Program.cs en un proyecto de consola, luego ejecute dotnet run. ```csharp using System; using System.Net.Http; using System.Net.Http.Headers; using System.Text; using System.Text.Json; string RequiredEnv(string name) => !string.IsNullOrWhiteSpace(Environment.GetEnvironmentVariable(name)) ? Environment.GetEnvironmentVariable(name)! : throw new InvalidOperationException($"Set {name}"); var apiKey = RequiredEnv("GENDERAPI_API_KEY"); using var handler = new HttpClientHandler { AllowAutoRedirect = false }; using var client = new HttpClient(handler) { Timeout = TimeSpan.FromSeconds(30) }; using var request = new HttpRequestMessage(HttpMethod.Get, "https://api.genderapi.io/api/v2/usage"); request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", apiKey); using var response = await client.SendAsync(request); var raw = await response.Content.ReadAsStringAsync(); if (!(response.Content.Headers.ContentType?.MediaType?.Contains("json") ?? false)) throw new InvalidOperationException($"HTTP {(int)response.StatusCode}: expected JSON"); using var result = JsonDocument.Parse(raw); if (!response.IsSuccessStatusCode) { Console.Error.WriteLine(result.RootElement); // Preserve Problem Details. Environment.ExitCode = 1; } else { Console.WriteLine(result.RootElement); // For batches, inspect every item even on HTTP 200. } ``` **Go** Go 1.22+; biblioteca estándar. Guarde como main.go y ejecute go run main.go. ```go package main import ( "encoding/json" "fmt" "io" "net/http" "os" "strings" "time" ) func requiredEnv(name string) string { value := os.Getenv(name) if value == "" { panic("Set " + name) } return value } func run() error { apiKey := requiredEnv("GENDERAPI_API_KEY") request, err := http.NewRequest("GET", "https://api.genderapi.io/api/v2/usage", nil) if err != nil { return err } request.Header.Set("Authorization", "Bearer " + apiKey) client := &http.Client{ Timeout: 30 * time.Second, CheckRedirect: func(req *http.Request, via []*http.Request) error { return http.ErrUseLastResponse }, } response, err := client.Do(request) if err != nil { return err } defer response.Body.Close() raw, err := io.ReadAll(response.Body) if err != nil { return err } if !strings.Contains(response.Header.Get("Content-Type"), "json") || !json.Valid(raw) { return fmt.Errorf("HTTP %d: expected a JSON response", response.StatusCode) } if response.StatusCode < 200 || response.StatusCode >= 300 { return fmt.Errorf("HTTP %d: %s", response.StatusCode, raw) } fmt.Println(string(raw)) // For batches, inspect every item even on HTTP 200. return nil } func main() { if err := run(); err != nil { fmt.Fprintln(os.Stderr, err) // Keep Problem Details for error handling. os.Exit(1) } } ``` - [Tarifas de IA por modo](https://www.genderapi.io/es/docs/v2/ai-options) - [Facturación y reintentos no confirmados](https://www.genderapi.io/es/docs/v2/errors-and-retries)