# Tareas y espera limitada

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

Fuente: https://scifig.ai/es/docs/api/jobs

## 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`.

```json
{
  "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 resultado | Presente | Significado |
| --- | --- | --- |
| file_id | always | Pásalo a otro punto de acceso o a `GET /files/{file_id}` |
| format | always | Extensión del archivo de salida, como `png`, `svg` o `pdf` |
| width, height | Resultados PNG | Dimensiones en píxeles |
| download_url, expires_at | always | Enlace firmado, válido durante una hora |
| editor_url | tareas de gráficos y diagramas de flujo | Abre el resultado en su espacio de trabajo del sitio web; las ilustraciones y conversiones no tienen este enlace |

## Ciclo de estados

| status | Significado |
| --- | --- |
| queued | Aceptada y esperando capacidad |
| processing | En ejecución |
| succeeded | Terminada; los `outputs` están listos y los créditos cobrados |
| failed | No produjo ningún resultado; `error.code` indica el motivo y se devuelve la reserva |
| canceled | Detenida antes de terminar; créditos devueltos |

| `error.code` de una tarea fallida | Significado | Qué hacer |
| --- | --- | --- |
| TASK_TIMED_OUT | La 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_REJECTED | La 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_INCOMPLETE | La 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_FOUND | La tarea se admitió, pero ya no se encuentra su ejecución. | Envía una solicitud nueva con una clave nueva |
| TASK_FAILED | La 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_ERROR | La 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

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

## JavaScript

```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

```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())
```