SDK de Conversión de Archivos para C# y .NET#

Enconvert es el cliente oficial de C# y .NET para la API de EnConvert, publicado en NuGet y dirigido a .NET 8 o posterior. Convierte archivos desde C#: URL a PDF, DOCX a PDF, HEIC a WebP, JSON a YAML, cualquier documento a Markdown y sitios web completos en un único ZIP. El mismo cliente lleva un espacio de nombres V2 para web scraping e inteligencia web, así que una sola clave cubre perceive, discover, lookup, distill, ingest y watch. Cada llamada es asíncrona y cancelable, cada respuesta es un record tipado, y el paquete no arrastra ninguna dependencia de terceros.

Instalación#

dotnet add package Enconvert

El ensamblado apunta a net8.0 con los tipos de referencia anulables habilitados y está construido únicamente sobre System.Net.Http y System.Text.Json.

Inicio rápido#

using Enconvert;

using var client = new EnconvertClient(Environment.GetEnvironmentVariable("ENCONVERT_API_KEY")!);

// Convierte una página en vivo a PDF y transmítela a disco.
var pdf = await client.ConvertUrlToPdfAsync("https://example.com", new UrlToPdfOptions { SaveTo = "page.pdf" });
Console.WriteLine(pdf.PresignedUrl);

// Lee una página como debería hacerlo tu agente, con una puntuación de calidad adjunta.
var op = await client.V2.PerceiveAsync("https://example.com", new PerceiveOptions { Outputs = new[] { "markdown", "structured" } });
Console.WriteLine($"{op.Outputs["markdown"].Url} scored {op.RenderQuality}");

EnconvertClient implementa IDisposable, así que decláralo con using o regístralo como singleton. Se autentica con una clave de API privada, lo que significa que su sitio es el servidor: nunca envíes la clave dentro de una build de escritorio, móvil o Blazor WebAssembly. La configuración de claves se trata en Autenticación.

Qué expone el cliente#

client.V2 agrupa 23 métodos repartidos en seis capacidades:

Cada método admite un CancellationToken opcional al final. Las opciones son records con propiedades init, así que constrúyelas con un inicializador de objeto y reutilízalas con with. Los clientes de otros lenguajes están en el índice de SDK; la superficie REST en crudo está en Visión general de endpoints.

Conversión de archivos#

ConvertUrlToPdfAsync#

Renderiza a PDF cualquier URL accesible.

var result = await client.ConvertUrlToPdfAsync("https://example.com", new UrlToPdfOptions
{
    SinglePage = false,
    ViewportWidth = 1440,
    PdfOptions = new PdfOptions { PageSize = "A4", Orientation = "landscape" },
    SaveTo = "report.pdf",
});

Console.WriteLine($"{result.Filename} ({result.FileSize} bytes)");

ConvertUrlToScreenshotAsync#

Captura un PNG de cualquier URL.

await client.ConvertUrlToScreenshotAsync("https://example.com", new UrlToScreenshotOptions
{
    ViewportWidth = 1440,
    SaveTo = "screenshot.png",
});

UrlToScreenshotOptions acepta las mismas opciones de viewport, medios, desplazamiento, nombre de archivo y acceso que ConvertUrlToPdfAsync, menos SinglePage y PdfOptions.

ConvertUrlToMarkdownAsync#

Extrae Markdown limpio con sabor GitHub desde una URL. Se eliminan la navegación, los pies de página, los anuncios y los scripts, se conserva el cuerpo principal del artículo y se antepone un frontmatter YAML (title, description, url, links, images).

await client.ConvertUrlToMarkdownAsync("https://example.com/article", new UrlToMarkdownOptions { SaveTo = "article.md" });

UrlToMarkdownOptions comparte las mismas opciones de renderizado y acceso. Para lecturas orientadas a agentes que además necesiten una puntuación de calidad y extracción estructurada, usa Perceive en su lugar.

ConvertImageAsync#

Convierte entre jpeg, png, svg, heic y webp en cualquier dirección, y rasteriza un PDF a JPEG.

// Desde una ruta.
await client.ConvertImageAsync("photo.heic", new ConvertImageOptions { OutputFormat = "webp", SaveTo = "photo.webp" });

// Desde bytes, con un nombre de archivo explícito para poder detectar el formato de entrada.
var bytes = await File.ReadAllBytesAsync("scan.pdf");
await client.ConvertImageAsync(new FileInput(bytes, "scan.pdf"), new ConvertImageOptions
{
    OutputFormat = "jpeg",
    SaveTo = "scan.jpeg",
});

Tres sobrecargas aceptan una ruta string, un byte[] en crudo o un record FileInput. El formato de entrada procede de la extensión del nombre de archivo, así que prefiere FileInput cuando tengas bytes: la sobrecarga de byte[] pelado envía upload.bin, que solo funciona en los endpoints con detección automática.

Los pares no admitidos lanzan ArgumentException antes de realizar ninguna solicitud HTTP, así que una errata no cuesta nada.

ConvertDocumentAsync#

Convierte documentos y formatos de datos. OutputFormat es "pdf" por defecto.

// docx a pdf
await client.ConvertDocumentAsync("report.docx", new ConvertDocumentOptions { SaveTo = "report.pdf" });

// json a yaml
await client.ConvertDocumentAsync("data.json", new ConvertDocumentOptions { OutputFormat = "yaml", SaveTo = "data.yaml" });

// markdown a pdf con geometría de página
await client.ConvertDocumentAsync("README.md", new ConvertDocumentOptions
{
    PdfOptions = new PdfOptions { PageSize = "A4", Margins = new PdfMargins { Top = 20, Bottom = 20 } },
    SaveTo = "readme.pdf",
});

Entradas admitidas: .doc, .docx, .xls, .xlsx, .ppt, .pptx, .html, .htm, .odt, .ods, .odp, .ots, .pages, .numbers, .md, .markdown, .csv, .json, .xml, .yaml, .yml, .toml. EPUB no tiene un par de documento propio, así que envía .epub a través de ConvertToPdfAsync o ConvertToMarkdownAsync.

Igual que ConvertImageAsync, este método tiene sobrecargas de ruta, byte[] y FileInput.

ConvertToMarkdownAsync#

Envía casi cualquier documento al endpoint de Markdown con detección automática: PDF, DOCX, PPTX, XLSX, CSV, HTML, EPUB, TXT y MD, además de formatos ofimáticos heredados y ODF. Aquí las imágenes no están admitidas.

await client.ConvertToMarkdownAsync("handbook.docx", new ConvertToMarkdownOptions { SaveTo = "handbook.md" });

El formato se detecta en el servidor, así que no hay comprobación de extensión en el cliente ni opciones de PDF en este endpoint. ConvertToMarkdownOptions lleva únicamente SaveTo y OutputFilename. La salida es un único archivo .md consciente de los encabezados, lo que lo convierte en una primera etapa sólida de un pipeline de RAG: un troceador semántico puede dividir por la propia jerarquía de encabezados del documento en lugar de por recuentos arbitrarios de caracteres.

ConvertToPdfAsync#

El otro endpoint con detección automática: formatos ofimáticos, ODF, Pages, Numbers, RTF, CSV, HTML, Markdown, texto plano, imágenes rasterizadas, SVG, EPUB o un PDF existente que se pasa directamente para normalizarlo.

// Diapositivas a PDF.
await client.ConvertToPdfAsync("slides.pptx", new ConvertToPdfOptions { SaveTo = "slides.pdf" });

// PDF de paso directo, convertido a escala de grises.
await client.ConvertToPdfAsync("scan.pdf", new ConvertToPdfOptions
{
    PdfOptions = new PdfOptions { Grayscale = true },
    SaveTo = "gray.pdf",
});

ConvertToPdfOptions lleva SaveTo, OutputFilename y PdfOptions, y tiene las mismas tres sobrecargas de entrada que los métodos anteriores.

Lotes de sitios completos#

ConvertWebsiteToPdfAsync y ConvertWebsiteToScreenshotAsync descubren todas las páginas de un sitio, convierten cada una en segundo plano y empaquetan los resultados en un único ZIP. Ambos son únicamente asíncronos y requieren una clave de API privada.

var batch = await client.ConvertWebsiteToPdfAsync("https://example.com", new WebsiteToPdfOptions
{
    CrawlMode = "sitemap",
    ExcludePatterns = new[] { "/blog/tag/" },
    NotificationEmail = "[email protected]",
});
Console.WriteLine($"{batch.BatchId}: {batch.UrlCount} pages via {batch.DiscoveryMethod}");

// Bloquea hasta que el ZIP esté listo, luego guárdalo.
var status = await client.WaitForBatchAsync(batch.BatchId, new WaitForBatchOptions { SaveTo = "site.zip" });
Console.WriteLine($"{status.Completed} of {status.Total} converted, {status.Failed} failed");

Para sondear según tu propio calendario, llama a GetBatchStatusAsync(batchId) y lee ZipDownloadUrl en cuanto Status salga de "processing".

WaitForBatchOptions toma IntervalMs (por defecto 5_000), TimeoutMs (por defecto 1_800_000, es decir 30 minutos) y SaveTo. Reventar el plazo lanza ApiException con estado 504.

GetJobStatusAsync#

Sondea un único job de conversión por id.

var status = await client.GetJobStatusAsync("job_abc123");

if (status.Status == "success") Console.WriteLine(status.PresignedUrl);
else if (status.Status == "failed") Console.Error.WriteLine(status.Error);

Pares de conversión admitidos#

El SDK refleja el mapa de conversores del gateway e implementa 43 pares {input}-to-{output} tipados.

La clase estática Formats expone la misma tabla, así que puedes validar antes de construir una interfaz o una cola de jobs:

Formats.ValidOutputsFor("json");        // ["csv", "toml", "xml", "yaml"]
Formats.ValidOutputsFor("pdf");         // ["jpeg"]
Formats.ImplementedConversions;         // el conjunto completo de los 43 nombres de endpoint
Formats.NormalizeOutputFormat(".JPG");  // "jpeg"

Cualquier cosa fuera de esta tabla pasa por ConvertToPdfAsync o ConvertToMarkdownAsync, que detectan el formato en el servidor. La referencia completa de parámetros vive en Parámetros y opciones.

Inteligencia web (V2)#

Cada lectura V2 lleva RenderQuality, una puntuación de 0.0 a 1.0 que indica con qué honestidad se renderizó la página. Un desafío antibots, un muro de cookies o de inicio de sesión, un error HTTP o el armazón vacío de una aplicación de una sola página vuelven con una puntuación baja, un mapa Deductions relleno que nombra qué comprobaciones saltaron y una lista Warnings, mientras que el contenido se sigue devolviendo. De eso se trata: una mala lectura queda marcada en lugar de entrar en silencio en el contexto de tu agente. La misma puntuación aparece en los resultados de perceive, en los elementos de distill, en los resultados de lookup percibidos automáticamente y en los snapshots de los watchers. Los conceptos se tratan en la visión general de V2. Los endpoints V2 requieren una clave de API privada; las claves públicas se rechazan.

Perceive#

Renderiza una URL en artefactos listos para agentes.

var op = await client.V2.PerceiveAsync("https://example.com", new PerceiveOptions
{
    Outputs = new[] { "markdown", "screenshot", "structured" },
    Extract = new[] { "tables", "metadata" },
    OnlyMainContent = true,
});

Console.WriteLine(op.RenderQuality);            // de 0.0 a 1.0
Console.WriteLine(op.StatusCode);               // estado HTTP del origen
Console.WriteLine(op.Outputs["markdown"].Url);  // firmada durante 15 minutos
Console.WriteLine(op.Structured);               // JsonObject, la forma es tuya

foreach (var (check, penalty) in op.Deductions) Console.WriteLine($"deduction {check}: {penalty}");

ProxyUrl, Geolocation y ActionChain existen en PerceiveOptions pero todavía no están disponibles en el servidor y actualmente vuelven como 422.

Vuelve a firmar las URL de artefacto más adelante, agrupa hasta 1000 URL o transmite bytes sin la ida y vuelta de la URL firmada:

// Las URL de artefacto se vuelven a firmar en cada obtención de la operación.
var again = await client.V2.GetPerceiveOperationAsync(op.OperationId);

// Lotes: los pequeños se ejecutan en línea, los más grandes devuelven "queued" y los sondeas.
var batch = await client.V2.PerceiveBatchAsync(
    new[] { "https://a.example.com", "https://b.example.com" },
    new PerceiveBatchOptions { Outputs = new[] { "markdown" }, OutputMode = "zip" });

var done = await client.V2.GetPerceiveBatchAsync(batch.JobId);
Console.WriteLine($"{done.Completed}/{done.Total} done, {done.Failed} failed, zip {done.Zip?.Url}");

// Descarga directa: se requiere exactamente una salida que produzca artefacto.
var direct = await client.V2.PerceiveDirectAsync("https://example.com", new PerceiveOptions { Outputs = new[] { "pdf" } });
await File.WriteAllBytesAsync(direct.Filename ?? "page.pdf", direct.Content);

// Vuelve a descargar un artefacto almacenado de una operación anterior.
var artifact = await client.V2.DownloadPerceiveArtifactAsync(op.OperationId, "markdown");

PerceiveDirectAsync lanza ArgumentException localmente a menos que se pida exactamente uno de markdown, html_cleaned, html_raw, screenshot, screenshot_full_page, pdf, links o images, ya que structured es JSON en línea y no un archivo almacenado. Ambos métodos directos devuelven un PerceiveDirectResult que lleva Content, ContentType, Filename, OperationId, ObjectKey, CacheHit, RenderQuality, SourceStatusCode, ContentHash y WarningsCount. DownloadPerceiveArtifactAsync toma el nombre de la salida solo cuando la operación produjo más de un artefacto, y devuelve 410 una vez que el artefacto supera su ventana de retención.

Discover#

Enumera las URL de un sitio sin renderizado en navegador, lo que lo hace mucho más barato que un rastreo.

var found = await client.V2.DiscoverAsync("https://example.com", new DiscoverOptions
{
    Mode = "hybrid",
    MaxUrls = 200,
    ExcludePatterns = new[] { "/tag/" },
});

Console.WriteLine($"{found.Total} urls, truncated: {found.Truncated}");
foreach (var url in found.Urls) Console.WriteLine(url);

DiscoverResult informa de Total, Urls, PagesCrawled, Truncated, RobotsRespected, un mapa de recuentos por origen en Sources y Warnings.

Lookup#

Ejecuta una búsqueda web por categorías y, opcionalmente, renderiza los primeros resultados en la misma llamada.

var search = await client.V2.LookupAsync("best static site generators", new LookupOptions
{
    Category = "web",
    NumResults = 10,
    TimeFilter = "month",
    PerceiveTop = 3,
});

foreach (var hit in search.Results)
{
    Console.WriteLine($"{hit.Position}. {hit.Title} {hit.Url}");
    if (hit.Perceive is { } page)
        Console.WriteLine($"   quality {page.RenderQuality}, markdown {page.Outputs["markdown"].Url}");
}

LookupResult también lleva AnswerBox, KnowledgeGraph, PerceiveOperationIds y Warnings.

Distill#

Extracción estructurada guiada por schema. Cuando proporcionas uno, se ejecuta primero una pasada CSS gratuita, y solo los campos que se le escapan escalan al nivel del LLM.

using System.Text.Json.Nodes;

var extraction = await client.V2.DistillAsync(new DistillOptions
{
    Urls = new[] { "https://example.com/pricing" },
    Schema = new JsonObject { ["plans"] = "list of plan names with monthly prices" },
    CssSchema = new CssSchema
    {
        BaseSelector = ".plan-card",
        Fields = new[]
        {
            new CssField { Name = "name", Type = "text", Selector = "h3" },
            new CssField { Name = "price", Type = "text", Selector = ".price" },
        },
    },
});

var first = extraction.Results[0];
Console.WriteLine($"{first.Data} via {first.ExtractionTier}");
Console.WriteLine($"css fields {first.FieldsFromCss}, llm fields {first.FieldsFromLlm}");

// O descubre primero un sitio y luego destila cada página que encuentre.
await client.V2.DistillAsync(new DistillOptions
{
    DiscoverFrom = new DistillDiscoverFrom { Url = "https://example.com", Mode = "sitemap", MaxPages = 10 },
    Schema = new JsonObject { ["title"] = "page title" },
});

CssField.Type es uno de text, attribute, html, regex, nested, list o nested_list, con anidamiento de hasta cinco niveles de profundidad. Pasar Urls y DiscoverFrom a la vez, o ninguno de los dos, lanza ArgumentException antes de que salga ninguna solicitud.

Ingest#

Convierte un sitio entero, o un montón de documentos subidos, en JSONL troceado que un almacén vectorial pueda leer. Ingest siempre es asíncrono.

// Desde un sitio.
var job = await client.V2.IngestAsync(new IngestOptions
{
    Mode = "sitemap",
    Url = "https://docs.example.com",
    MaxPages = 100,
    Chunk = new IngestChunkOptions { MaxWords = 512 },
    WebhookUrl = "https://my.app/hooks/enconvert",
});

// Desde archivos subidos: PDF, DOCX, PPTX, XLSX, CSV, HTML, EPUB, TXT y MD, ofimática heredada y ODF.
var fileJob = await client.V2.IngestFilesAsync(
    new[] { new FileInput(await File.ReadAllBytesAsync("handbook.pdf"), "handbook.pdf") },
    new IngestFilesOptions { Chunk = new IngestChunkOptions { MaxWords = 512 } });

// Sondea hasta que el JSONL esté listo.
var status = await client.V2.GetIngestJobAsync(job.JobId);
Console.WriteLine($"{status.Status}: {status.PagesProcessed}/{status.PagesDiscovered} pages, {status.TotalChunks} chunks");
if (status.Status == "completed") Console.WriteLine(status.OutputUrl);

var recent = await client.V2.ListIngestJobsAsync(new V2ListOptions { Limit = 20 });
await client.V2.CancelIngestJobAsync(job.JobId); // idempotente

Las reglas de modo se imponen en el cliente, así que un job urls que además establece Url lanza ArgumentException de inmediato. Un job pasa por queued, discovering, processing y luego completed, failed o canceled. La entrega del webhook se puede verificar de extremo a extremo:

var secret = await client.V2.GetWebhookSecretAsync();
Console.WriteLine($"{secret.SignatureHeader} using {secret.SignatureScheme}, replay tolerance {secret.ReplayToleranceSeconds}s");

await client.V2.RotateWebhookSecretAsync();  // las firmas antiguas dejan de verificarse
var retry = await client.V2.RetryIngestWebhookAsync(job.JobId);
Console.WriteLine($"delivered: {retry.Delivered} after {retry.Attempts} attempts");

Watch#

Vuelve a renderizar una página según un calendario y te avisa cuando cambia.

var watcher = await client.V2.CreateWatcherAsync("https://example.com/pricing", new WatchCreateOptions
{
    FrequencyMinutes = 60,
    DiffMode = "auto",
    WebhookUrl = "https://my.app/hooks/changes",
});

var page = await client.V2.ListWatchersAsync(new V2ListOptions { Limit = 20 });
var one = await client.V2.GetWatcherAsync(watcher.WatcherId);
var history = await client.V2.GetWatcherSnapshotsAsync(watcher.WatcherId, new SnapshotListOptions { Limit = 10 });
foreach (var snap in history.Snapshots)
    Console.WriteLine($"{snap.CheckedAt} changed: {snap.HasChanges} similarity: {snap.Similarity}");

await client.V2.UpdateWatcherAsync(watcher.WatcherId, new WatcherUpdate { Status = "paused" });
await client.V2.UpdateWatcherAsync(watcher.WatcherId, new WatcherUpdate { WebhookUrl = "" }); // lo borra
await client.V2.DeleteWatcherAsync(watcher.WatcherId); // borrado lógico, idempotente

WatcherUpdate también acepta Status ("active" o "paused") y lanza ArgumentException si le pasas una actualización sin ningún campo establecido.

Opciones de PDF#

PdfOptions es compartido por ConvertUrlToPdfAsync, ConvertDocumentAsync, ConvertToPdfAsync (solo escala de grises) y PerceiveOptions cuando pdf está entre las salidas.

await client.ConvertUrlToPdfAsync("https://internal.example.com/report", new UrlToPdfOptions
{
    PdfOptions = new PdfOptions
    {
        PageSize = "A4",
        Orientation = "landscape",
        Margins = new PdfMargins { Top = 10, Bottom = 10, Left = 15, Right = 15 },
        Scale = 0.9,
        Header = new PdfHeaderFooter { Content = "Quarterly Report", Height = 15 },
        Footer = new PdfHeaderFooter { Content = "Confidential", Height = 12 },
    },
    Auth = new HttpBasicAuth { Username = "user", Password = "pass" },
    SaveTo = "report.pdf",
});

Manejo de errores#

Todo fallo aflora como una excepción tipada, así que los bloques catch se leen de lo más específico a lo menos específico.

using Enconvert;

try
{
    await client.V2.PerceiveAsync("https://example.com");
}
catch (AuthenticationException) { Console.Error.WriteLine("Invalid or missing API key."); }
catch (QuotaException) { Console.Error.WriteLine("Request rejected with 402."); }
catch (RateLimitException) { Console.Error.WriteLine("Too many requests, back off and retry."); }
catch (ApiException e) { Console.Error.WriteLine($"API error [{e.StatusCode}]: {e.Message}"); }

La jerarquía va de EnconvertException a ApiException (que lleva StatusCode) y de ahí a las tres clases específicas, así que un único catch (EnconvertException) captura todo lo que lanza el SDK. Los mensajes se toman del campo detail o error del cuerpo de la respuesta cuando está presente. La validación que el SDK hace localmente, como un par de conversión no admitido o una solicitud de distill malformada, lanza ArgumentException en su lugar y nunca llega a la red. Los códigos de respuesta están catalogados en Códigos de error.

Recuperación de timeouts#

Los renderizados de URL largos y las conversiones de documentos grandes pueden sobrevivir a un timeout de proxy inverso de 60 a 120 segundos incluso cuando la conversión en sí tiene éxito. El cliente absorbe eso por ti:

1. Antes de cada conversión de un solo archivo o de una sola URL, el SDK genera un id de job y lo envía con la solicitud.
2. Si esa solicitud vuelve con 5xx, el SDK pasa a sondear GET /v1/convert/status/{jobId} cada 3 segundos en lugar de fallar.
3. Un job registrado como success devuelve el ConversionResult normal. Un job registrado como failed lanza ApiException con estado 500 y el mensaje de error del servidor.
4. El plazo de sondeo es de 5 minutos, tras lo cual el SDK lanza ApiException(504, "Conversion timed out").

Esto cubre ConvertUrlToPdfAsync, ConvertUrlToScreenshotAsync, ConvertUrlToMarkdownAsync y los cuatro métodos de subida de archivos. Los envíos de lotes de sitios web quedan fuera deliberadamente, porque un envío fallido no tiene fila de job que sondear y debe aflorar de inmediato. Cuando una respuesta omite job_id, el SDK rellena el id que generó, de modo que ConversionResult.JobId siempre se puede usar con GetJobStatusAsync.

Configuración#

using var client = new EnconvertClient(
    apiKey: Environment.GetEnvironmentVariable("ENCONVERT_API_KEY")!,
    baseUrl: null,       // por defecto https://api.enconvert.com
    timeoutMs: 300_000);

La clave viaja en un encabezado X-API-Key en cada solicitud. Las descargas de artefactos van directamente a URL de almacenamiento firmadas mediante un segundo HttpClient que no envía clave ni aplica timeout, así que un ZIP grande puede transmitirse todo el tiempo que necesite. Libera el cliente una sola vez al final de tu proceso, o regístralo como singleton en lugar de construir uno por solicitud.

Forma del resultado#

Cada método de conversión devuelve un ConversionResult:

public sealed record ConversionResult
{
    public required string PresignedUrl { get; init; }  // URL de descarga firmada
    public required string ObjectKey { get; init; }     // clave del objeto en almacenamiento
    public required string Filename { get; init; }      // nombre de archivo del servidor
    public int? FileSize { get; init; }                 // bytes
    public double? ConversionTimeSeconds { get; init; }
    public string? JobId { get; init; }                 // usable con GetJobStatusAsync
}

El trabajo asíncrono devuelve sus propios records: JobStatus (Status, PresignedUrl, ObjectKey, Error), BatchSubmission (BatchId, Status, UrlCount, TotalDiscovered, DiscoveryMethod, OutputFormat) y BatchStatus (recuentos agregados, OutputMode, ZipDownloadUrl y los Items por URL).

Los artefactos V2 llegan como valores V2OutputArtifact indexados por nombre de salida, cada uno con Url (firmada durante 15 minutos), ObjectKey, SizeBytes, ContentType y ExpiresIn (900 segundos por defecto). Las URL firmadas caducan, así que para acceso permanente descarga los bytes (pasa SaveTo, usa PerceiveDirectAsync o descarga la URL tú mismo) y guárdalos en tu propio bucket. Llamar de nuevo a GetPerceiveOperationAsync vuelve a firmar las URL de artefacto de una operación que siga dentro de su ventana de retención.

Código fuente e incidencias#

• NuGet: Enconvert
• GitHub: conversionapi/csharp-sdk
• Licencia: MIT
• Otros lenguajes: índice de SDK · Claves de API: panel de control · precios

Preguntas frecuentes#

¿Cómo convierto archivos en C# con un paquete de NuGet?#

Ejecuta dotnet add package Enconvert, crea un cliente con tu clave (new EnconvertClient(apiKey)) y llama a un método asíncrono como ConvertUrlToPdfAsync, ConvertImageAsync o ConvertDocumentAsync. Pasa SaveTo en el record de opciones para transmitir la salida directamente a una ruta local, o lee result.PresignedUrl para descargarla tú mismo.

¿Cómo convierto una URL a PDF en .NET?#

Llama a await client.ConvertUrlToPdfAsync("https://example.com", new UrlToPdfOptions { SaveTo = "page.pdf" }). Establece SinglePage = false para paginar, y pasa un record PdfOptions para el tamaño de página, la orientación, los márgenes, la escala, la escala de grises, el encabezado y el pie. El viewport es de 1920 x 1080 por defecto.

¿Cómo convierto DOCX a PDF en C#?#

Llama a ConvertDocumentAsync("report.docx", new ConvertDocumentOptions { SaveTo = "report.pdf" }). PDF es el formato de salida por defecto, así que OutputFormat es opcional aquí. El mismo método gestiona entradas XLSX, PPTX, ODF, Pages, Numbers, HTML, Markdown, CSV, JSON, XML, YAML y TOML.

¿Cómo extraigo el contenido de una página web con el SDK de C#?#

Usa el espacio de nombres V2: await client.V2.PerceiveAsync(url, new PerceiveOptions { Outputs = new[] { "markdown", "structured" } }). Obtienes Markdown, HTML limpio o en crudo, capturas de pantalla, PDF, enlaces, imágenes y extracción estructurada, cada uno como artefacto firmado, más una puntuación RenderQuality para la lectura. Para enumerar primero las URL de un sitio sin renderizar nada, llama a DiscoverAsync.

¿Qué significa la calidad de renderizado y por qué está en cada lectura?#

RenderQuality es una puntuación de honestidad de 0.0 a 1.0 adjunta a cada lectura V2. Una puntuación baja significa que la página no se renderizó limpiamente: un desafío antibots, un muro de cookies o de inicio de sesión, un error HTTP o el armazón vacío de una aplicación de una sola página. El contenido sigue llegando, junto con un mapa Deductions que nombra qué comprobaciones saltaron y una lista Warnings, para que tu agente pueda rechazar una mala lectura en lugar de tratarla como un hecho.

¿Gestiona el SDK las conversiones que superan el timeout del proxy?#

Sí. Envía un id de job generado con cada conversión de un solo archivo o de una sola URL y, si la solicitud devuelve 5xx, sondea GET /v1/convert/status/{jobId} cada 3 segundos durante hasta 5 minutos. El éxito devuelve el resultado normal, un fallo registrado lanza ApiException, y agotar el plazo lanza ApiException(504, "Conversion timed out"). Los envíos de lotes de sitios web quedan excluidos a propósito.

¿Puedo usar este SDK desde Blazor WebAssembly o desde una aplicación móvil?#

No. El cliente se autentica con una clave de API privada que nunca debe viajar en código que un usuario pueda leer. Ejecútalo desde ASP.NET Core, un worker service, una Azure Function o cualquier otro host .NET 8 del lado del servidor, y haz que tu front end llame a tu propio endpoint en su lugar.

¿Qué conversiones de imagen están admitidas?#

Todos los pares entre jpeg, png, svg, heic y webp, que son 20 combinaciones, más la rasterización de pdf a jpeg. El formato de entrada procede de la extensión del nombre de archivo, y los pares no admitidos lanzan ArgumentException antes de cualquier llamada de red. Consulta la tabla tú mismo con Formats.ValidOutputsFor("heic").

¿Cómo convierto un sitio de documentación en fragmentos listos para RAG?#

Llama a client.V2.IngestAsync(new IngestOptions { Mode = "sitemap", Url = "https://docs.example.com", MaxPages = 100 }), luego sondea GetIngestJobAsync hasta que Status sea "completed" y lee OutputUrl para obtener el JSONL. Para documentos locales, IngestFilesAsync pasa las subidas por el mismo troceador. Ajusta Chunk.MaxWords y Chunk.SentenceOverlap para que encajen con tu modelo de embeddings.

¿Cuánto tiempo son válidas las URL de descarga?#

Las URL de artefacto de V2 se firman durante 15 minutos (ExpiresIn es de 900 segundos) y se vuelven a firmar cada vez que obtienes la operación con GetPerceiveOperationAsync. Los resultados de conversión también devuelven una URL prefirmada. En ambos casos, si necesitas que el archivo sobreviva a la firma, descárgalo y guárdalo en tu propio bucket.