Documentación de la API
SOC 2 CertifiedISO 27001GDPR Compliant

API de Detección de Texto Generado por IA

Documentación completa para integrar la API de detección de IA de TruthScan en sus aplicaciones.

Pruébala sin código visitando nuestro endpoint FastAPI: https://detect-text.truthscan.com/docs

Autenticación

TruthScan usa claves de API para permitir el acceso a la API. Puede obtener su clave de API en la parte superior de la página en nuestro portal de desarrolladores.

TruthScan espera que la clave de API se incluya en todas las solicitudes de API al servidor en un cuerpo de solicitud que se ve así:

{
  "key": "YOUR API KEY GOES HERE"
}

Debe reemplazar YOUR API KEY GOES HERE con su clave de API personal.

Para escenarios de web socket, necesitará enviar su Organization ID como parte de la URL. Puede obtener su Organization ID en la parte superior de la página en nuestro portal de desarrolladores.

TruthScan espera que su Organization ID se incluya en la URL de todas las solicitudes de web socket. La documentación se verá así:

wss://detect-text.truthscan.com/ws/$ORG_ID

Debe reemplazar $ORG_ID con su Organization ID personal.

Detector de IA

Detectar

Este endpoint le permite enviar texto para detección de IA. Se recomiendan al menos 200 palabras para obtener la mejor precisión.

POST https://detect-text.truthscan.com/detect

Umbral

Este endpoint devuelve una puntuación "result" de 1-100. Para obtener la mejor precisión, cualquier puntuación por debajo de 50 se considera definitivamente humana. 50-60 es posible IA. Por encima de 60 es IA definitiva. Este es el resultado más preciso, con 99%+ de precisión.

Las puntuaciones de otros detectores, como Writer y Copyleaks, son aproximadas y no tan precisas como la puntuación principal "result".

Saltos de línea

Si está enviando datos como JSON, los saltos de línea deben codificarse como \n dentro de la cadena.

Ejemplo de Solicitud

curl -X 'POST' \
  'https://detect-text.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "text": "On Citizen science\nCitizen science involves the public participating in scientific research. This can take many forms, collecting data on local wildlife populations to analyzing astronomical images. Citizen science projects allow researchers to gather large amounts of data and engage the public in the process. By participating, individuals contribute to valuable research while gaining a deeper understanding of the scientific world around them.",
  "key": "YOUR-API-KEY-GOES-HERE",
  "model": "xlm_ud_detector",
  "retry_count": 0
}'

Aquí, la entrada de la solicitud debe ser inferior a 30.000 palabras.

Ejemplo de Respuesta

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "input": "Citizen science involves the public participating in scientific research. This can take many forms, collecting data on local wildlife populations to analyzing astronomical images. Citizen science projects allow researchers to gather large amounts of data and engage the public in the process. By participating, individuals contribute to valuable research while gaining a deeper understanding of the scientific world around them.",
    "model": "xlm_ud_detector",
    "result": null,
    "result_details": null,
    "status": "pending",
    "retry_count": 0
}

La respuesta contiene el ID asignado por el servidor del documento. En este punto, el documento está en cola para procesamiento. Puede usar el endpoint de la API /query para consultar el estado de la solicitud de detección de IA. El tiempo promedio para completar una verificación de detección de IA es entre 2-4 segundos. Puede tardar más dependiendo del conteo de palabras.

Consultar

Este endpoint acepta un ID de documento devuelto por la solicitud /detect. Y devuelve el estado del envío del documento, así como el resultado de la operación de detección de IA según lo manejado por varios detectores de IA de terceros.

POST https://detect-text.truthscan.com/query

Ejemplo de Solicitud

curl -X 'POST' \
  'https://detect-text.truthscan.com/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "DOCUMENT-ID-GOES-HERE"
}'

Ejemplo de Respuesta

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "model": "xlm_ud_detector",
    "result": 12.0,
    "result_details": {
        "scoreGptZero": 50.0,
        "scoreOpenAI": 0.0,
        "scoreWriter": 0.0,
        "scoreCrossPlag": 0.0,
        "scoreCopyLeaks": 50.0,
        "scoreSapling": 0.0,
        "scoreContentAtScale": 0.0,
        "scoreZeroGPT": 50.0,
        "human": 88.0
    },
    "status": "done",
    "retry_count": 0
}

Aquí, "result": 12.0 indica la humanidad de la entrada. Esto significa que, dado que es menor que el umbral del 50%, el texto es definitivamente humano. De manera similar, los valores bajo result_details indican la humanidad de la entrada. Por ejemplo, "scoreZeroGPT": 50.0 significa que el texto probablemente es 50% escrito por humanos según ZeroGPT. Lo mismo se aplica al resto de los otros detectores.

Verificar Créditos del Usuario

Este endpoint acepta el apikey del usuario a través del encabezado. Y devuelve los detalles de créditos del usuario.

GET https://detect-text.truthscan.com/check-user-credits

Ejemplo de Solicitud

curl -X 'GET' \
  'https://detect-text.truthscan.com/check-user-credits' \
  -H 'apikey: YOUR API KEY GOES HERE' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json'

Ejemplo de Respuesta

{
    "baseCredits": 10000,
    "boostCredits": 1000,
    "credits": 11000
}

Detección de IA a Nivel de Oración

El detector de IA a nivel de oración se ejecuta sobre un protocolo basado en WebSocket.

Aquí están los pasos necesarios para obtener resultados a nivel de oración para su texto:

  • Conectar al WebSocket
  • Escuchar todos los eventos recibidos del WebSocket
  • Enviar una solicitud document_watch
  • Recibir un evento document_id
  • Tomar el id generado por la respuesta document_id y enviar un documento para detección de IA
  • Comenzar a recibir eventos document_chunk. Los eventos document_chunk devolverán cada oración junto con el resultado a nivel de oración
  • Cuando el documento termine el procesamiento, recibirá un evento document_done

Conectar al WebSocket

Este endpoint le permite establecer la conexión WebSocket

wss://detect-text.truthscan.com/ws/$ORG_ID

Código de Ejemplo

ws = new WebSocket("wss://detect-text.truthscan.com/ws/1722238709737x2194626580942121212");

Escuchar todos los eventos recibidos del WebSocket

Una vez que se establezca la conexión WebSocket, escuche los eventos enviados a través de la conexión WebSocket.

Código de Ejemplo

ws.addEventListener("message", (event) => {
  console.log("Message from server ", event.data);
});

Enviar una solicitud document_watch

Envíe interés en enviar un documento enviando una solicitud document_watch en el WebSocket

Código de Ejemplo

ws.send(JSON.stringify({
    "event_type": "document_watch",
    "api_key": "$API_KEY",
}))

Recibir un evento document_id

Después de enviar un evento document_watch, el servidor devuelve un evento document_id.

Ejemplo de Respuesta

{
  "event_type": "document_id",
  "success": true,
  "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa"
}

Enviar una Solicitud de Detección de IA

Tome el id generado por la respuesta document_id y envíe un documento para detección de IA

POST https://detect-text.truthscan.com/detect

Ejemplo de Solicitud

curl -X 'POST' \
  'https://detect-text.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "text": "Citizen science involves the public participating in scientific research. This can take many forms, collecting data on local wildlife populations to analyzing astronomical images. Citizen science projects allow researchers to gather large amounts of data and engage the public in the process. By participating, individuals contribute to valuable research while gaining a deeper understanding of the scientific world around them.",
  "key": "YOUR-API-KEY-GOES-HERE",
  "model": "xlm_ud_detector",
  "id": "512da191-166926922-44cb-81c6-191ae3a807aa"
}'

Recibir resultados a nivel de oración

Comience a recibir eventos document_chunk. Los eventos document_chunk devolverán cada oración junto con el resultado a nivel de oración

Ejemplo de Respuesta

{
    "event_type": "document_chunk",
    "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa",
    "model": "xlm_ud_detector",
    "chunk": "Citizen science involves the public in scientific research.",
    "result": 0.714
}

Cuando el documento termine el procesamiento, recibirá un evento document_done.

Ejemplo de Respuesta

{
    "event_type": "document_done",
    "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa",
    "model": "xlm_ud_detector"
}

Manejo de circunstancias excepcionales

Si por alguna razón el servidor encuentra un error al realizar la detección de IA, se enviará un evento document_error al cliente websocket. El cliente debe actuar adecuadamente, por ejemplo, una UI mostrará un mensaje de error.

Por ejemplo, el servidor enviará un código de error REQUEST_TIMEOUT cuando tome más de 20 segundos entre eventos de chunk.

{
    "event_type": "document_error",
    "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa",
    "error_code": "REQUEST_TIMEOUT",
    "message": "Request timeout. Took 20 seconds."
}

Cancelaciones

Habrá instancias en las que la UI querrá cancelar la operación. El usuario decide cerrar la ventana o cancela el evento explícitamente

Cuando esto suceda, debe enviar un evento document_halt

Ejemplo de Respuesta

{
    "event_type": "document_halt",
    "document_id": "512da191-166926922-44cb-81c6-191ae3a807aa"
}

Errores

La mayoría de los errores serán por parámetros incorrectos enviados a la API. Verifique nuevamente los parámetros de cada llamada de API para asegurarse de que esté formateado correctamente e intente ejecutar el código de ejemplo proporcionado.

Los códigos de error genéricos que usamos se ajustan al estándar REST:

Código de ErrorSignificado
400Bad Request -- Su solicitud es inválida.
403Forbidden -- La clave de API es inválida o no hay créditos suficientes (0,1 por palabra).
404Not Found -- El recurso especificado no existe.
405Method Not Allowed -- Intentó acceder a un recurso con un método inválido.
406Not Acceptable -- Solicitó un formato que no es JSON.
410Gone -- El recurso en este endpoint ha sido eliminado.
422Invalid Request Body -- El cuerpo de su solicitud está formateado incorrectamente o es inválido o tiene parámetros faltantes.
429Too Many Requests -- ¡Está enviando demasiadas solicitudes! ¡Reduzca la velocidad!
500Internal Server Error -- Tuvimos un problema con nuestro servidor. Intente nuevamente más tarde.
503Service Unavailable -- Estamos temporalmente fuera de línea para mantenimiento. Intente nuevamente más tarde.

Problemas Comunes y Soluciones

Problemas de Autenticación

"Verificación de usuario fallida" (403)

Causa: Clave de API inválida o expirada

Solución:

  1. Verifique que su clave de API sea correcta
  2. Verifique si su clave de API está activa en su cuenta
  3. Intente regenerar su clave de API

"No hay créditos suficientes" (403)

Causa: Créditos insuficientes para procesamiento de texto

Solución:

  1. Verifique sus créditos restantes usando /check-user-credits
  2. Compre créditos adicionales si es necesario
  3. Use entradas de texto más cortas para consumir menos créditos

Problemas de Validación de Entrada

"El texto de entrada no puede estar vacío" (400)

Causa: Texto vacío o solo con espacios en blanco enviado

Solución:

  1. Asegúrese de que su entrada de texto no esté vacía
  2. Elimine cualquier espacio en blanco inicial/final
  3. Verifique si la codificación de texto es correcta

"El correo electrónico de entrada está vacío" (400)

Causa: Correo electrónico faltante para procesamiento de URL

Solución:

  1. Proporcione una dirección de correo electrónico válida al enviar URLs
  2. Verifique que el formato del correo electrónico sea correcto

Problemas de Procesamiento

"Tiempo de espera de la solicitud" (WebSocket)

Causa: El procesamiento del documento tardó demasiado (>120 segundos)

Solución:

  1. Intente con una entrada de texto más pequeña
  2. Verifique si el servicio está experimentando alta carga
  3. Vuelva a intentar la solicitud

Estado del Documento "fallido"

Causa: El procesamiento falló por varias razones

Solución:

  1. Verifique si el texto de entrada cumple con los requisitos mínimos
  2. Verifique que el texto esté en un formato compatible
  3. Intente con un modelo diferente
  4. Contacte al soporte si el problema persiste

Problemas de Conexión WebSocket

Caídas de Conexión

Causa: Problemas de red o desconexiones del servidor

Solución:

  1. Verifique su conexión de red
  2. Implemente lógica de reconexión
  3. Verifique que la URL del WebSocket sea correcta

"Usuario no encontrado" (WebSocket)

Causa: Organization ID inválido en la conexión WebSocket

Solución:

  1. Verifique que el Organization ID sea correcto
  2. Asegúrese de que la cuenta del usuario esté activa
  3. Reautentique si es necesario

¿Necesita Ayuda?

Para obtener más información sobre cómo usar nuestra API o para soporte técnico, contáctenos.

Contáctenos

Preguntas Frecuentes sobre la API

Encuentre respuestas a las preguntas más comunes sobre nuestra API de detección de IA.