Vai al contenuto
Documentazione per sviluppatori

L’API v1 e il server MCP

Tutto ciò che ti serve per chiamare l’API: come autenticarti, ogni endpoint con richiesta e risposta, errori e limiti, ed esempi in curl, JavaScript e Python.

In questa pagina

Per iniziare

Panoramica

L’API ha la versione nel percorso, /api/v1. Ogni endpoint accetta un POST con un corpo JSON e risponde in JSON, anche in caso di errore.

URL di base https://blurwrite.com

Solo sul sito, non nell’API: il contatore di parole, il contatore di caratteri, il rilevatore di plagio e l’opzione "Più tempo per la riscrittura" dell’humanizer.

Generato dal documento OpenAPI, elenca esattamente le route e i campi accettati dall’API. Il documento OpenAPI

La tua prima chiamata

Un testo deve contenere almeno 50 parole.

Controlla "calibrated" prima di tutto: quando è false, la lingua non ha ancora una curva calibrata, quindi il valore non deve essere usato come risultato.

Per ogni valore viene mostrato il tipo. Una risposta reale contiene la valutazione del tuo testo.

Richiesta di esempio
curl -X POST https://blurwrite.com/api/v1/detect \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Il comitato si è riunito martedì per esaminare il progetto della nuova biblioteca. I membri hanno concordato che la sala lettura dovrebbe restare aperta più a lungo nei giorni feriali e hanno chiesto al personale di preparare un budget per le ore aggiuntive. La prossima riunione esaminerà i costi, il numero previsto di visitatori e l’impatto sul resto dell’edificio."}'
Risposta di esempio
{
  "figure": "number, da 0 a 100",
  "low": "number, da 0 a 100",
  "high": "number, da 0 a 100",
  "uncertainty": "number",
  "verdict": "human | uncertain | ai",
  "confidence": "low | medium | high",
  "sentences": [
    {
      "text": "string",
      "score": "number, da 0 a 1",
      "verdict": "human | uncertain | ai"
    }
  ],
  "words": "integer",
  "language": "string",
  "model": "string",
  "calibrated": "boolean",
  "bandHumanFlagRate": "number | null",
  "usage": {
    "recorded": "boolean",
    "words": "integer",
    "source": "plan | balance | plan_and_balance",
    "fromPlan": "integer",
    "fromBalance": "integer",
    "allowanceLeft": "integer | null",
    "balance": "integer"
  }
}

Autenticazione

Invia la tua chiave nell’header Authorization come token bearer. Una chiave nell’URL viene rifiutata.

Una chiave ha ambiti di autorizzazione: detect, rewrite, summarize e grammar. Una route risponde con 403 out_of_scope quando la chiave non dispone dell’ambito richiesto.

Autenticazione
Authorization: Bearer YOUR_API_KEY

Endpoint

POST /api/v1/detect

Analizza un testo. La valutazione del rilevatore per un testo: un valore da 0 a 100, l’intervallo attorno al valore, una valutazione per frase e l’indicazione della calibrazione della lingua.

Ambito della chiave: detect

Corpo della richiesta

CampoTipoObbligatorioDescrizione
textstringsìIl testo da analizzare o riscrivere.
languagestringnoIl codice della lingua, ad esempio "en" o "de". Se omesso, viene rilevato dal testo.
contentTypestringnoIl tipo di testo, ad esempio "essay" o "email", quando l’analisi deve usare la curva di quel tipo di testo.

Risposta

CampoTipoDescrizione
figurenumberLa valutazione da 0 a 100: quanto è probabile che il testo sia stato scritto da una macchina.
lownumberIl limite inferiore dell’intervallo attorno al valore.
highnumberIl limite superiore dell’intervallo attorno al valore.
uncertaintynumberMetà dell’ampiezza dell’intervallo, in punti.
verdictstringLa fascia in cui rientra il valore; una fascia, mai una conclusione su chi ha scritto il testo. Uno tra: human, uncertain, ai.
confidencestringQuanto è affidabile la valutazione. Uno tra: low, medium, high.
sentencesarray di SentenceScoreUna valutazione per frase.
wordsintegerLe parole analizzate.
languagestringLa lingua usata per analizzare il testo.
modelstringIl modello che ha prodotto la valutazione.
calibratedbooleanIndica se la lingua ha una curva calibrata. Quando è false, il valore non deve essere usato come risultato.
bandHumanFlagRatenumber | nullLa frequenza con cui i testi umani in questa fascia sono stati classificati come generati da una macchina nelle nostre misurazioni, oppure null.
usageUsageIl consumo conteggiato per questa chiamata.

Errori aggiuntivi di questa route

StatoCodiceSignificato
400no_textIl corpo non contiene "text".
422too_shortIl testo è più corto della lunghezza minima.
413text_too_longIl testo è più lungo di quanto il motore possa analizzare in una chiamata. Dividilo. Nessuna parola è stata conteggiata.
422not_calibratedQuesta lingua non può ancora essere analizzata.
503engine_unavailableIl motore non ha risposto. Nessuna parola è stata conteggiata.
502engine_unavailableIl motore non ha risposto. Nessuna parola è stata conteggiata.
503engine_startingIl motore è in fase di avvio e non è stato pronto in tempo. Nessuna parola è stata conteggiata. Riprova tra un minuto.
503engine_busyIl motore era occupato e l’analisi non è potuta iniziare in tempo; le analisi Pro sul sito hanno la precedenza sulle chiamate API. Nessuna parola è stata conteggiata. Riprova tra poco.
504engine_timeoutIl motore non ha completato l’analisi del testo in tempo. Nessuna parola è stata conteggiata. Riprova o invia un testo più breve.
429concurrency_limitedQuesta chiave ha già raggiunto il massimo di chiamate simultanee di questo tipo. Attendi che una termini o che trascorra il tempo indicato in Retry-After.
Richiesta di esempio
curl -X POST https://blurwrite.com/api/v1/detect \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Il comitato si è riunito martedì per esaminare il progetto della nuova biblioteca. I membri hanno concordato che la sala lettura dovrebbe restare aperta più a lungo nei giorni feriali e hanno chiesto al personale di preparare un budget per le ore aggiuntive. La prossima riunione esaminerà i costi, il numero previsto di visitatori e l’impatto sul resto dell’edificio."}'
Risposta di esempio
{
  "figure": "number, da 0 a 100",
  "low": "number, da 0 a 100",
  "high": "number, da 0 a 100",
  "uncertainty": "number",
  "verdict": "human | uncertain | ai",
  "confidence": "low | medium | high",
  "sentences": [
    {
      "text": "string",
      "score": "number, da 0 a 1",
      "verdict": "human | uncertain | ai"
    }
  ],
  "words": "integer",
  "language": "string",
  "model": "string",
  "calibrated": "boolean",
  "bandHumanFlagRate": "number | null",
  "usage": {
    "recorded": "boolean",
    "words": "integer",
    "source": "plan | balance | plan_and_balance",
    "fromPlan": "integer",
    "fromBalance": "integer",
    "allowanceLeft": "integer | null",
    "balance": "integer"
  }
}

POST /api/v1/detect/batch

Analizza più testi. Più testi in una sola chiamata, fino al limite del batch. La chiamata richiede in anticipo una quota sufficiente per le parole di ogni testo che può analizzare (50 parole o più); le parole dei testi che non restituiscono una valutazione vengono riaccreditate in seguito. L’errore di un testo non fa mai fallire l’intero batch.

Ambito della chiave: detect

Corpo della richiesta

CampoTipoObbligatorioDescrizione
itemsarray di objectsìI testi, ciascuno con il proprio "text" e i campi facoltativi "id", "language" e "contentType".
items[].idstringnoIl tuo id per l’elemento, restituito insieme al risultato. Se omesso, viene usata la posizione dell’elemento.
items[].textstringsìIl testo da analizzare o riscrivere.
items[].languagestringnoIl codice della lingua, ad esempio "en" o "de". Se omesso, viene rilevato dal testo.
items[].contentTypestringnoIl tipo di testo, ad esempio "essay" o "email", quando l’analisi deve usare la curva di quel tipo di testo.

Risposta

CampoTipoDescrizione
resultsarray di BatchResultUn risultato per elemento, nell’ordine di invio.
usageUsageIl consumo conteggiato per questa chiamata.

Errori aggiuntivi di questa route

StatoCodiceSignificato
400batch_emptyIl corpo non contiene "items" oppure l’elenco è vuoto.
413batch_too_largeIl batch contiene più elementi del limite consentito.
429concurrency_limitedQuesta chiave ha già raggiunto il massimo di chiamate simultanee di questo tipo. Attendi che una termini o che trascorra il tempo indicato in Retry-After.
Richiesta di esempio
curl -X POST https://blurwrite.com/api/v1/detect/batch \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"id":"1","text":"Il comitato si è riunito martedì per esaminare il progetto della nuova biblioteca. I membri hanno concordato che la sala lettura dovrebbe restare aperta più a lungo nei giorni feriali e hanno chiesto al personale di preparare un budget per le ore aggiuntive. La prossima riunione esaminerà i costi, il numero previsto di visitatori e l’impatto sul resto dell’edificio."},{"id":"2","text":"Il comitato si è riunito martedì per esaminare il progetto della nuova biblioteca. I membri hanno concordato che la sala lettura dovrebbe restare aperta più a lungo nei giorni feriali e hanno chiesto al personale di preparare un budget per le ore aggiuntive. La prossima riunione esaminerà i costi, il numero previsto di visitatori e l’impatto sul resto dell’edificio."}]}'
Risposta di esempio
{
  "results": [
    {
      "id": "string",
      "detection": {
        "figure": "number, da 0 a 100",
        "low": "number, da 0 a 100",
        "high": "number, da 0 a 100",
        "uncertainty": "number",
        "verdict": "human | uncertain | ai",
        "confidence": "low | medium | high",
        "sentences": [
          {
            "text": "string",
            "score": "number, da 0 a 1",
            "verdict": "human | uncertain | ai"
          }
        ],
        "words": "integer",
        "language": "string",
        "model": "string",
        "calibrated": "boolean",
        "bandHumanFlagRate": "number | null"
      },
      "error": {
        "code": "string",
        "message": "string"
      }
    }
  ],
  "usage": {
    "recorded": "boolean",
    "words": "integer",
    "source": "plan | balance | plan_and_balance",
    "fromPlan": "integer",
    "fromBalance": "integer",
    "allowanceLeft": "integer | null",
    "balance": "integer"
  }
}

POST /api/v1/humanize

Umanizza un testo. L’humanizer con le sue verifiche dei fatti: numeri, nomi e citazioni vengono conservati, mentre una riscrittura che altera un fatto viene corretta o segnalata. La modalità "custom" (Pro) scrive nel tuo stile, ricavato da un campione della tua scrittura.

Tramite l’API l’humanizer esegue la riscrittura standard. "Più tempo per la riscrittura" è disponibile solo sul sito.

Ambito della chiave: rewrite

Corpo della richiesta

CampoTipoObbligatorioDescrizione
textstringsìIl testo da analizzare o riscrivere.
modestringnoLa modalità di riscrittura. Uno tra: natural, formal, simple, academic, creative, shorten, expand, custom. Predefinito: natural.
style_samplestringnoCon la modalità "custom": un campione della tua scrittura, da 150 a 2000 parole, analizzato sul server. Se omesso, viene usato il campione salvato nel tuo account.
tabstringnoLa scheda dell'humanizer: il registro usato nella riscrittura. Standard mantiene il registro del testo originale. Uno tra: standard, academic, professional, casual. Predefinito: standard.
strengthstringnoRegolare mantiene il contenuto e il registro. Aggressiva può riordinare il testo e tralasciare gli approfondimenti, ma conserva tutti i punti principali; alcune parti potrebbero risultare insolite. Uno tra: regular, aggressive. Predefinito: regular.
ownTouchstringnoUn dettaglio, un esempio o un’opinione con parole tue, fino a 400 caratteri, da integrare nella riscrittura.
languagestringnoIl codice della lingua, ad esempio "en" o "de". Se omesso, viene rilevato dal testo.

Risposta

CampoTipoDescrizione
textstringIl testo riscritto.
beforeDetectionLa valutazione del rilevatore sul tuo testo, oppure null se non disponibile.
afterDetectionLa valutazione del rilevatore sulla riscrittura, oppure null.
passesintegerQuante riscritture sono state prodotte prima di scegliere questa.
factsobjectCosa hanno rilevato le verifiche dei fatti e, in caso di problemi, perché la riscrittura non le ha superate.
latebooleanTrue quando la riscrittura è stata restituita al raggiungimento del limite di tempo, con le verifiche incomplete.
usageUsageIl consumo conteggiato per questa chiamata.

Errori aggiuntivi di questa route

StatoCodiceSignificato
400no_textIl corpo non contiene "text".
422too_shortIl testo è più corto della lunghezza minima.
400unknown_modeLa modalità non è tra quelle offerte da questa route.
400unknown_optionLa scheda o l’intensità non è disponibile per questo endpoint.
402plan_requiredLa modalità, la scheda, l’intensità o il tocco personale richiedono un piano che l’account non ha; la modalità "custom" richiede Pro. Nessuna parola è stata conteggiata.
400no_sampleLa modalità "custom" richiede un campione di scrittura, inviato o salvato nell’account.
400sample_too_shortIl campione di scrittura è più corto della lunghezza minima.
400sample_too_longIl campione di scrittura supera la lunghezza massima.
429concurrency_limitedQuesta chiave ha già raggiunto il massimo di chiamate simultanee di questo tipo. Attendi che una termini o che trascorra il tempo indicato in Retry-After.
422no_rewriteIl motore ha risposto, ma nessuna bozza ha superato i controlli (vuota, un rifiuto o una copia del testo). Nessuna parola è stata conteggiata.
503timeoutLa riscrittura ha impiegato troppo tempo ed è stata interrotta. Nessuna parola è stata conteggiata.
503engine_unavailableIl motore non ha risposto. Nessuna parola è stata conteggiata.
502engine_unavailableIl motore non ha risposto. Nessuna parola è stata conteggiata.
Richiesta di esempio
curl -X POST https://blurwrite.com/api/v1/humanize \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Il comitato si è riunito martedì per esaminare il progetto della nuova biblioteca. I membri hanno concordato che la sala lettura dovrebbe restare aperta più a lungo nei giorni feriali e hanno chiesto al personale di preparare un budget per le ore aggiuntive. La prossima riunione esaminerà i costi, il numero previsto di visitatori e l’impatto sul resto dell’edificio."}'
Risposta di esempio
{
  "text": "string",
  "before": {
    "figure": "number, da 0 a 100",
    "low": "number, da 0 a 100",
    "high": "number, da 0 a 100",
    "uncertainty": "number",
    "verdict": "human | uncertain | ai",
    "confidence": "low | medium | high",
    "sentences": [
      {
        "text": "string",
        "score": "number, da 0 a 1",
        "verdict": "human | uncertain | ai"
      }
    ],
    "words": "integer",
    "language": "string",
    "model": "string",
    "calibrated": "boolean",
    "bandHumanFlagRate": "number | null"
  },
  "after": {
    "figure": "number, da 0 a 100",
    "low": "number, da 0 a 100",
    "high": "number, da 0 a 100",
    "uncertainty": "number",
    "verdict": "human | uncertain | ai",
    "confidence": "low | medium | high",
    "sentences": [
      {
        "text": "string",
        "score": "number, da 0 a 1",
        "verdict": "human | uncertain | ai"
      }
    ],
    "words": "integer",
    "language": "string",
    "model": "string",
    "calibrated": "boolean",
    "bandHumanFlagRate": "number | null"
  },
  "passes": "integer",
  "facts": "object",
  "late": "boolean",
  "usage": {
    "recorded": "boolean",
    "words": "integer",
    "source": "plan | balance | plan_and_balance",
    "fromPlan": "integer",
    "fromBalance": "integer",
    "allowanceLeft": "integer | null",
    "balance": "integer"
  }
}

POST /api/v1/paraphrase

Parafrasa un testo. Lo strumento di parafrasi, con lo stesso elenco di modalità dello strumento sul sito.

Ambito della chiave: rewrite

Corpo della richiesta

CampoTipoObbligatorioDescrizione
textstringsìIl testo da analizzare o riscrivere.
modestringnoLa modalità di riscrittura. Uno tra: standard, fluency, formal, academic, simple, creative, expand, shorten. Predefinito: standard.
strengthstringnoQuanto la riscrittura può discostarsi dall’originale. Uno tra: readable, balanced, strong. Predefinito: balanced.
readabilitystringnoIl registro da usare nella scrittura. Uno tra: casual, professional, academic, creative. Predefinito: professional.
purposestringnoLo scopo del testo. Uno tra: general, essay, article, email, marketing, report, story. Predefinito: general.
synonymsstringnoQuanto liberamente si possono sostituire le parole. Uno tra: few, some, many. Predefinito: some.
freezeWordsarray di stringnoParole e frasi che devono essere restituite esattamente come scritte: al massimo 25, ciascuna fino a 60 caratteri. Le loro parole rientrano nel conteggio della chiamata.
customInstructionstringnoUna tua breve istruzione per la riscrittura, fino a 500 caratteri. Le sue parole rientrano nel conteggio della chiamata.
languagestringnoIl codice della lingua, ad esempio "en" o "de". Se omesso, viene rilevato dal testo.
closedLoopbooleannoImposta false per saltare il ciclo di verifica. Predefinito: true.

Risposta

CampoTipoDescrizione
textstringIl testo riscritto.
beforeDetectionLa valutazione del rilevatore sul tuo testo, oppure null se non disponibile.
afterDetectionLa valutazione del rilevatore sulla riscrittura, oppure null.
passesintegerQuante riscritture sono state prodotte prima di scegliere questa.
factsobjectCosa hanno rilevato le verifiche dei fatti e, in caso di problemi, perché la riscrittura non le ha superate.
latebooleanTrue quando la riscrittura è stata restituita al raggiungimento del limite di tempo, con le verifiche incomplete.
usageUsageIl consumo conteggiato per questa chiamata.

Errori aggiuntivi di questa route

StatoCodiceSignificato
400no_textIl corpo non contiene "text".
422too_shortIl testo è più corto della lunghezza minima.
400unknown_modeLa modalità non è tra quelle offerte da questa route.
400option_invalidfreezeWords non è un elenco di parole o frasi. Non è stato conteggiato nulla.
400option_too_longfreezeWords o customInstruction supera il proprio limite. Non è stato conteggiato nulla.
429concurrency_limitedQuesta chiave ha già raggiunto il massimo di chiamate simultanee di questo tipo. Attendi che una termini o che trascorra il tempo indicato in Retry-After.
422no_rewriteIl motore ha risposto, ma nessuna bozza ha superato i controlli (vuota, un rifiuto o una copia del testo). Nessuna parola è stata conteggiata.
503timeoutLa riscrittura ha impiegato troppo tempo ed è stata interrotta. Nessuna parola è stata conteggiata.
503engine_unavailableIl motore non ha risposto. Nessuna parola è stata conteggiata.
502engine_unavailableIl motore non ha risposto. Nessuna parola è stata conteggiata.
Richiesta di esempio
curl -X POST https://blurwrite.com/api/v1/paraphrase \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Il comitato si è riunito martedì per esaminare il progetto della nuova biblioteca. I membri hanno concordato che la sala lettura dovrebbe restare aperta più a lungo nei giorni feriali e hanno chiesto al personale di preparare un budget per le ore aggiuntive. La prossima riunione esaminerà i costi, il numero previsto di visitatori e l’impatto sul resto dell’edificio."}'
Risposta di esempio
{
  "text": "string",
  "before": {
    "figure": "number, da 0 a 100",
    "low": "number, da 0 a 100",
    "high": "number, da 0 a 100",
    "uncertainty": "number",
    "verdict": "human | uncertain | ai",
    "confidence": "low | medium | high",
    "sentences": [
      {
        "text": "string",
        "score": "number, da 0 a 1",
        "verdict": "human | uncertain | ai"
      }
    ],
    "words": "integer",
    "language": "string",
    "model": "string",
    "calibrated": "boolean",
    "bandHumanFlagRate": "number | null"
  },
  "after": {
    "figure": "number, da 0 a 100",
    "low": "number, da 0 a 100",
    "high": "number, da 0 a 100",
    "uncertainty": "number",
    "verdict": "human | uncertain | ai",
    "confidence": "low | medium | high",
    "sentences": [
      {
        "text": "string",
        "score": "number, da 0 a 1",
        "verdict": "human | uncertain | ai"
      }
    ],
    "words": "integer",
    "language": "string",
    "model": "string",
    "calibrated": "boolean",
    "bandHumanFlagRate": "number | null"
  },
  "passes": "integer",
  "facts": "object",
  "late": "boolean",
  "usage": {
    "recorded": "boolean",
    "words": "integer",
    "source": "plan | balance | plan_and_balance",
    "fromPlan": "integer",
    "fromBalance": "integer",
    "allowanceLeft": "integer | null",
    "balance": "integer"
  }
}

POST /api/v1/summarize

Riassumi un testo. Lo strumento di riassunto, con frasi chiave, un paragrafo o un elenco puntato.

Ambito della chiave: summarize

Corpo della richiesta

CampoTipoObbligatorioDescrizione
textstringsìIl testo da analizzare o riscrivere.
modestringnoLa forma del riassunto. Uno tra: key-sentences, paragraph, bullets. Predefinito: key-sentences.
lengthstringnoLa lunghezza del riassunto. Uno tra: short, medium, long. Predefinito: medium.

Risposta

CampoTipoDescrizione
textstringIl riassunto.
usageUsageIl consumo conteggiato per questa chiamata.

Errori aggiuntivi di questa route

StatoCodiceSignificato
400no_textIl corpo non contiene "text".
422too_shortIl testo è più corto della lunghezza minima.
429concurrency_limitedQuesta chiave ha già raggiunto il massimo di chiamate simultanee di questo tipo. Attendi che una termini o che trascorra il tempo indicato in Retry-After.
503timeoutLa riscrittura ha impiegato troppo tempo ed è stata interrotta. Nessuna parola è stata conteggiata.
503engine_unavailableIl motore non ha risposto. Nessuna parola è stata conteggiata.
502engine_unavailableIl motore non ha risposto. Nessuna parola è stata conteggiata.
Richiesta di esempio
curl -X POST https://blurwrite.com/api/v1/summarize \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Il comitato si è riunito martedì per esaminare il progetto della nuova biblioteca. I membri hanno concordato che la sala lettura dovrebbe restare aperta più a lungo nei giorni feriali e hanno chiesto al personale di preparare un budget per le ore aggiuntive. La prossima riunione esaminerà i costi, il numero previsto di visitatori e l’impatto sul resto dell’edificio."}'
Risposta di esempio
{
  "text": "string",
  "usage": {
    "recorded": "boolean",
    "words": "integer",
    "source": "plan | balance | plan_and_balance",
    "fromPlan": "integer",
    "fromBalance": "integer",
    "allowanceLeft": "integer | null",
    "balance": "integer"
  }
}

POST /api/v1/grammar

Controlla la grammatica. Problemi di grammatica, ortografia, punteggiatura e stile, ciascuno con la sua posizione nel testo e le sostituzioni suggerite.

Ambito della chiave: grammar

Corpo della richiesta

CampoTipoObbligatorioDescrizione
textstringsìIl testo da analizzare o riscrivere.
languagestringnoIl codice della lingua per il controllo, ad esempio "en-US" o "de-DE". Predefinito: en-US.

Risposta

CampoTipoDescrizione
issuesarray di GrammarIssueI problemi rilevati, nell’ordine in cui compaiono.
usageUsageIl consumo conteggiato per questa chiamata.

Errori aggiuntivi di questa route

StatoCodiceSignificato
400no_textIl corpo non contiene "text".
503engine_unavailableIl motore non ha risposto. Nessuna parola è stata conteggiata.
502engine_unavailableIl motore non ha risposto. Nessuna parola è stata conteggiata.
503engine_startingIl motore è in fase di avvio e non è stato pronto in tempo. Nessuna parola è stata conteggiata. Riprova tra un minuto.
504engine_timeoutIl motore non ha completato l’analisi del testo in tempo. Nessuna parola è stata conteggiata. Riprova o invia un testo più breve.
Richiesta di esempio
curl -X POST https://blurwrite.com/api/v1/grammar \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Il comitato si è riunito martedì per esaminare il progetto della nuova biblioteca. I membri hanno concordato che la sala lettura dovrebbe restare aperta più a lungo nei giorni feriali e hanno chiesto al personale di preparare un budget per le ore aggiuntive. La prossima riunione esaminerà i costi, il numero previsto di visitatori e l’impatto sul resto dell’edificio."}'
Risposta di esempio
{
  "issues": [
    {
      "offset": "integer",
      "length": "integer",
      "message": "string",
      "shortMessage": "string",
      "category": "grammar | spelling | punctuation | style | typography",
      "replacements": [
        "string"
      ],
      "context": "string"
    }
  ],
  "usage": {
    "recorded": "boolean",
    "words": "integer",
    "source": "plan | balance | plan_and_balance",
    "fromPlan": "integer",
    "fromBalance": "integer",
    "allowanceLeft": "integer | null",
    "balance": "integer"
  }
}

Riferimento

Errori

Un errore risponde con il suo stato HTTP e un corpo in questa forma. Basati sul codice; il messaggio dice cosa non ha funzionato e cosa fare dopo.

Errori che ogni route può restituire

StatoCodiceSignificato
401key_in_urlLa chiave è stata inviata nell’URL. Inviala nell’header Authorization.
401no_keyNon è stata inviata alcuna chiave.
401bad_keyLa chiave non è valida o è stata revocata.
403out_of_scopeLa chiave non dispone dell’ambito richiesto da questa route.
429rate_limitedTroppe richieste per questa chiave. Attendi il tempo indicato in Retry-After.
403plan_lapsedIl piano dell’account non include più l’API.
413too_largeLa richiesta è troppo grande.
400bad_bodyIl corpo non è un oggetto JSON.
413too_many_wordsLa chiamata contiene più parole di quante ne accetti una singola chiamata. Suddividila. Non è stato conteggiato nulla.
402quota_exhaustedLe parole API del piano per questo periodo di fatturazione sono esaurite e il saldo delle ricariche è vuoto. Nessuna parola è stata conteggiata.
402quota_shortLa chiamata richiede più parole di quelle disponibili nella quota API del piano e nel saldo delle ricariche messi insieme. Nessuna parola è stata conteggiata.
402monthly_ceilingL’account ha raggiunto il limite dell’API per questo periodo di fatturazione, che si applica indipendentemente dal saldo. Nessuna parola è stata conteggiata.
503store_unavailableAl momento non è stato possibile leggere la chiave, il conteggio delle parole dell’account o il campione di scrittura salvato, oppure questa istanza non dispone di un archivio degli account. Nessuna operazione è stata eseguita e nessuna parola è stata conteggiata.

Una chiamata riserva le parole prima di essere eseguita e le restituisce se non riesce. Se in quel momento non è possibile aggiornare il conteggio, le parole restano addebitate: una chiamata non riuscita lo segnala e include "recorded": false nei dati di utilizzo, un batch risponde con "recorded": false nei dati di utilizzo e il conteggio delle parole non viene stimato.

Corpo dell’errore
{
  "error": {
    "code": "string",
    "message": "string",
    "docs": "string",
    "available": "integer"
  },
  "usage": {
    "recorded": "boolean",
    "words": "integer",
    "source": "plan | balance | plan_and_balance",
    "fromPlan": "integer",
    "fromBalance": "integer",
    "allowanceLeft": "integer | null",
    "balance": "integer"
  }
}

Limiti

Tutti i valori riportati qui sono quelli applicati dall’API.

  • Ogni chiave può effettuare al massimo 60 richieste ogni 60 secondi.
  • Ogni chiave può avere al massimo 4 chiamate di rilevamento (un batch conta come una sola chiamata) e 2 chiamate di umanizzazione, parafrasi o riassunto in esecuzione contemporaneamente; una chiamata aggiuntiva riceve la risposta 429 concurrency_limited con un header Retry-After.
  • Quando i motori sono occupati, le analisi degli account Pro del sito hanno la precedenza sulle chiamate API, quindi una chiamata API potrebbe dover attendere il proprio turno.
  • Un batch può contenere al massimo 50 testi.
  • Ogni chiamata accetta al massimo 20.000 parole, in un singolo testo o in un intero gruppo di testi.
  • Il rilevatore legge un testo di massimo 90.000 caratteri, circa 10.000 parole, con qualsiasi piano. Un testo più lungo restituisce 413 text_too_long, anche se rientra nel limite di parole della chiamata.
  • Un account può avere fino a 5 chiavi attive, così puoi sostituire una chiave senza interruzioni del servizio.

Oggetti di risposta

Gli oggetti restituiti dagli endpoint, campo per campo.

Detection

CampoTipoDescrizione
figurenumberLa valutazione da 0 a 100: quanto è probabile che il testo sia stato scritto da una macchina.
lownumberIl limite inferiore dell’intervallo attorno al valore.
highnumberIl limite superiore dell’intervallo attorno al valore.
uncertaintynumberMetà dell’ampiezza dell’intervallo, in punti.
verdictstringLa fascia in cui rientra il valore; una fascia, mai una conclusione su chi ha scritto il testo. Uno tra: human, uncertain, ai.
confidencestringQuanto è affidabile la valutazione. Uno tra: low, medium, high.
sentencesarray di SentenceScoreUna valutazione per frase.
wordsintegerLe parole analizzate.
languagestringLa lingua usata per analizzare il testo.
modelstringIl modello che ha prodotto la valutazione.
calibratedbooleanIndica se la lingua ha una curva calibrata. Quando è false, il valore non deve essere usato come risultato.
bandHumanFlagRatenumber | nullLa frequenza con cui i testi umani in questa fascia sono stati classificati come generati da una macchina nelle nostre misurazioni, oppure null.

SentenceScore

CampoTipoDescrizione
textstringLa frase.
scorenumberDa 0 a 1, quanto è probabile che la frase sia stata scritta da una macchina.
verdictstringLa fascia in cui rientra la frase. Uno tra: human, uncertain, ai.

Usage

CampoTipoDescrizione
recordedbooleanTrue quando il conteggio è stato registrato. False solo quando non è stato possibile riaccreditare le parole non analizzate di un batch; in quel caso è presente solo "words".
wordsintegerLe parole conteggiate per questa chiamata.
sourcestringDa dove provengono: dalle parole API del piano, dal saldo delle ricariche o da entrambi. Uno tra: plan, balance, plan_and_balance.
fromPlanintegerLe parole prelevate dalla quota API del piano. Presente quando recorded è true.
fromBalanceintegerLe parole prelevate dal saldo delle ricariche. Presente quando recorded è true.
allowanceLeftinteger | nullLe parole del piano rimaste per questo strumento dopo la chiamata, nel periodo di fatturazione corrente. Null per uno strumento senza quota in questo piano. Presente quando recorded è true.
balanceintegerIl saldo delle ricariche rimasto dopo questa chiamata. Presente quando recorded è true.

RewriteResult

CampoTipoDescrizione
textstringIl testo riscritto.
beforeDetectionLa valutazione del rilevatore sul tuo testo, oppure null se non disponibile.
afterDetectionLa valutazione del rilevatore sulla riscrittura, oppure null.
passesintegerQuante riscritture sono state prodotte prima di scegliere questa.
factsobjectCosa hanno rilevato le verifiche dei fatti e, in caso di problemi, perché la riscrittura non le ha superate.
latebooleanTrue quando la riscrittura è stata restituita al raggiungimento del limite di tempo, con le verifiche incomplete.

GrammarIssue

CampoTipoDescrizione
offsetintegerDove inizia il problema nel testo inviato, in unità di codice UTF-16 (un indice di stringa JavaScript).
lengthintegerQuante unità di codice UTF-16 del testo inviato copre il problema.
messagestringLa spiegazione dell’errore.
shortMessagestringLa stessa spiegazione, in poche parole.
categorystringIl tipo di problema. Uno tra: grammar, spelling, punctuation, style, typography.
replacementsarray di stringSostituzioni suggerite, dalla migliore.
contextstringIl testo attorno al problema.

BatchResult

CampoTipoDescrizione
idstringL’id dell’elemento.
detectionDetectionLa valutazione, quando l’elemento ne ha restituita una.
errorobjectPerché l’elemento non ha restituito una valutazione.

Error

CampoTipoDescrizione
errorobject
usageUsageIl consumo conteggiato per questa chiamata.
Server MCP

Il server MCP

Un agente può chiamare gli stessi strumenti tramite il Model Context Protocol. Il server è solo un client di questa API, quindi l'agente ottiene esattamente la stessa valutazione fornita dal sito.

  • detect_textAnalizza un testo.
  • detect_batchAnalizza più testi.
  • humanize_textUmanizza un testo verificandone i fatti.
  • paraphrase_textParafrasa un testo.
  • summarize_textRiassume un testo.
  • check_grammarControlla grammatica e ortografia.

Claude Code Si connette online

  1. Salva la tua chiave API in una variabile d’ambiente chiamata BLURWRITE_API_KEY, dove viene eseguito il client:

    export BLURWRITE_API_KEY="YOUR_API_KEY"
  2. Esegui questo comando in un terminale:

    claude mcp add --transport http blurwrite https://blurwrite.com/api/mcp --header "Authorization: Bearer $BLURWRITE_API_KEY"
  3. Oppure inserisci questo in .mcp.json:

    .mcp.json
    {
      "mcpServers": {
        "blurwrite": {
          "type": "http",
          "url": "https://blurwrite.com/api/mcp",
          "headers": {
            "Authorization": "Bearer ${BLURWRITE_API_KEY}"
          }
        }
      }
    }
  4. Verifica che funzioni: chiedi al tuo assistente "Controlla questo paragrafo con Blurwrite e dimmi l’intervallo e il livello di affidabilità."

La tua chiave API si trova nella dashboard, alla voce API. Non inserire mai una chiave in un file condiviso o in un repository.

Ogni valutazione ricevuta da un agente include il valore, il relativo margine di incertezza e lo stato della calibrazione, così l'agente può spiegare cosa significa la valutazione e quando non deve essere usata.

La tua chiave

Accedi, poi crea una chiave dalla tua dashboard.

Ottieni la tua chiave nella dashboard

Le chiavi non vengono mai create su questa pagina.

Cosa fanno l’API e il server MCP