SciFig
Comenzar gratis

Referencia de la API

Tareas y espera limitada

Consulta el estado, los créditos y los resultados, y espera una tarea sin consultas periódicas.

Ver como Markdown

Consultar una tarea#

GET /jobs/{id}, con el ámbito figures:read, devuelve el mismo objeto de tarea que la solicitud de creación. Las tareas de otras cuentas y los identificadores desconocidos devuelven 404 NOT_FOUND. GET /jobs?limit=10&cursor=… enumera tus tareas, de la más nueva a la más antigua; de 1 a 20 por página, sigue next_cursor.

{
  "id": "5f4a9a5e-fc45-4eae-9f9c-56b5f686cba5",
  "kind": "chart",
  "status": "succeeded",
  "created_at": "2026-10-14T11:20:05.000Z",
  "credits": { "reserved": 50, "charged": 50, "refunded": 0 },
  "outputs": [
    {
      "file_id": "0b7c…",
      "format": "png",
      "width": 2126,
      "height": 1417,
      "download_url": "https://scifig.ai/api/v1/files/0b7c…?exp=…&sig=…",
      "expires_at": "2026-10-14T12:21:40.000Z",
      "editor_url": "https://scifig.ai/app/datachart?conversation=…"
    }
  ],
  "error": null
}

kind es image_generation, image_edit, image_upscale, image_conversion, chart o flowchart. Las respuestas nunca incluyen tu descripción, tus entradas ni identificadores internos.

Campo del resultadoPresenteSignificado
file_idalwaysPásalo a otro punto de acceso o a GET /files/{file_id}
formatalwaysExtensión del archivo de salida, como png, svg o pdf
width, heightResultados PNGDimensiones en píxeles
download_url, expires_atalwaysEnlace firmado, válido durante una hora
editor_urltareas de gráficos y diagramas de flujoAbre el resultado en su espacio de trabajo del sitio web; las ilustraciones y conversiones no tienen este enlace

Ciclo de estados#

statusSignificado
queuedAceptada y esperando capacidad
processingEn ejecución
succeededTerminada; los outputs están listos y los créditos cobrados
failedNo produjo ningún resultado; error.code indica el motivo y se devuelve la reserva
canceledDetenida antes de terminar; créditos devueltos
`error.code` de una tarea fallidaSignificadoQué hacer
TASK_TIMED_OUTLa tarea ha superado el tiempo límite y se han devuelto los créditos. La generación o edición de una ilustración puede incluir late_delivery_until: hasta ese momento el resultado puede llegar gratis.Sigue consultando la tarea hasta late_delivery_until; en otro caso, envía una solicitud nueva con una clave nueva
CONTENT_REJECTEDLa política de contenido ha rechazado el resultado durante la ejecución; se han devuelto los créditos. El mismo código se devuelve como 422 cuando se rechaza la propia solicitud al crearla.Cambia la descripción o la entrada y usa una clave nueva
ADMISSION_INCOMPLETELa tarea nunca se inició porque un error que permite reintentar lo impidió. No se consumieron créditos.Envía la misma solicitud con el mismo Idempotency-Key
TASK_NOT_FOUNDLa tarea se admitió, pero ya no se encuentra su ejecución.Envía una solicitud nueva con una clave nueva
TASK_FAILEDLa tarea ha fallado y se han devuelto los créditos. Cualquier error del motor sin código público propio pasa a ser TASK_FAILED; el código del motor está en details.reason.Envía una solicitud nueva con una clave nueva
INTERNAL_ERRORLa tarea ha fallado sin indicar el motivo; se han devuelto los créditos.Envía una solicitud nueva con una clave nueva

succeeded, failed y canceled son estados finales, con una excepción: una generación o edición de ilustración fallida con TASK_TIMED_OUT incluye late_delivery_until. Hasta entonces el resultado puede llegar gratis y la tarea pasar a succeeded; sigue consultándola en lugar de crear otra.

Si no se puede leer una tarea de la lista, GET /jobs devuelve 503 SERVICE_UNAVAILABLE con Retry-After: 3; reintenta la solicitud de lista. No sustituye esa tarea por un resultado fallido.

Espera limitada#

  • Prefer: wait=N, de 1 a 30, en una solicitud de creación retiene la respuesta hasta que la tarea llegue a un estado final o pasen N segundos. Las tareas finalizadas devuelven 200; las que siguen ejecutándose devuelven 202 con Location: /api/v1/jobs/{id} y Retry-After.
  • Esperar no modifica la tarea: 202 no es un error y la tarea sigue ejecutándose después de la respuesta.
  • Consulta GET /jobs/{id} sin superar la frecuencia de Retry-After, 3 segundos. Las ilustraciones suelen terminar en 20–90 segundos y los gráficos y diagramas de flujo en 30–120 segundos.
  • Una tarea fallida también puede representar una solicitud rechazada: una creación rechazada con un error como 402 INSUFFICIENT_CREDITS o 422 CONTENT_REJECTED permanece en GET /jobs como tarea failed con ese código y sin créditos.
  • Las integraciones de servidor deben guardar el identificador de tarea antes de esperar, para que una conexión interrumpida nunca provoque una segunda tarea.

cURL#

curl https://scifig.ai/api/v1/jobs/<job_id> \
  -H "Authorization: Bearer $SCIFIG_API_KEY"

JavaScript#

const response = await fetch('https://scifig.ai/api/v1/jobs/<job_id>', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SCIFIG_API_KEY}`,
  },
});
const result = await response.json();
console.log(response.status, result);

Python#

import os

import requests

headers = {
    "Authorization": f"Bearer {os.environ['SCIFIG_API_KEY']}",
}
response = requests.get(
    "https://scifig.ai/api/v1/jobs/<job_id>",
    headers=headers,
    timeout=60,
)
print(response.status_code, response.json())
AnteriorCreación y edición de diagramas de flujoSiguienteCréditosLa API usa tus créditos de SciFig: un saldo para el sitio web, la API y MCP.