API Crear clave

Tu primera llamada en cuatro pasos.

Una API REST sencilla, JSON de entrada y de salida. Las dos primeras llamadas no cuestan nada: compruebas tu clave sin gastar un crédito.

  1. 01

    Consigue una clave

    Crea una clave y guárdala en tu servidor. Solo se muestra una vez.

    Tu terminal
    export STAGLIGHT_API_KEY="sl_live_..."
  2. 02

    Compruébala gratis

    Estas dos llamadas no cuestan nada: una te dice quién eres y tu saldo, la otra calcula el precio de una tarea.

    ¿Funciona mi clave?
    curl -s https://staglight.ai/api/v1/me \
      -H "Authorization: Bearer $STAGLIGHT_API_KEY"
    ¿Cuánto costará esta tarea?
    curl -s -X POST https://staglight.ai/api/v1/estimate \
      -H "Authorization: Bearer $STAGLIGHT_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"op": "image.nano-banana-pro", "params": {"prompt": "Foto de producto premium de un frasco de sérum de vidrio sobre piedra mojada, luz suave de ventana", "aspect_ratio": "4:5"}}'
  3. 03

    Ejecuta una tarea

    Un POST inicia Nano Banana Pro. Se cobra una vez; después este código espera el resultado y obtiene el archivo.

    Abrir Nano Banana Pro
    # 1. Crea el trabajo. Se cobra una vez y se reembolsa si falla.
    JOB_ID=$(curl -s -X POST https://staglight.ai/api/v1/jobs \
      -H "Authorization: Bearer $STAGLIGHT_API_KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: $(uuidgen)" \
      -d '{
        "op": "image.nano-banana-pro",
        "params": {
          "prompt": "Foto de producto premium de un frasco de sérum de vidrio sobre piedra mojada, luz suave de ventana",
          "aspect_ratio": "4:5"
        },
        "max_credits": 16
      }' | jq -r .id)
    
    # 2. Consulta hasta que termine. Cada llamada espera hasta 30 segundos.
    while :; do
      JOB=$(curl -s "https://staglight.ai/api/v1/jobs/$JOB_ID?wait=30" -H "Authorization: Bearer $STAGLIGHT_API_KEY")
      case "$(echo "$JOB" | jq -r .status)" in queued|running) ;; *) break ;; esac
    done
    
    # 3. Descarga el resultado desde outputs[0].download_url.
    DOWNLOAD_URL=$(echo "$JOB" | jq -r '.outputs[0].download_url')
    curl -L -o result.png "$DOWNLOAD_URL"
    import os, uuid, requests
    
    BASE = "https://staglight.ai/api/v1"
    HEADERS = {"Authorization": f"Bearer {os.environ['STAGLIGHT_API_KEY']}"}
    
    # 1. Crea el trabajo. Se cobra una vez y se reembolsa si falla.
    r = requests.post(f"{BASE}/jobs", timeout=60,
                      headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
                      json={
                        "op": "image.nano-banana-pro",
                        "params": {
                          "prompt": "Foto de producto premium de un frasco de sérum de vidrio sobre piedra mojada, luz suave de ventana",
                          "aspect_ratio": "4:5"
                        },
                        "max_credits": 16
                      })
    r.raise_for_status()
    job = r.json()
    
    # 2. Consulta hasta que termine. Cada llamada espera hasta 30 segundos.
    while job["status"] in ("queued", "running"):
        job = requests.get(f"{BASE}/jobs/{job['id']}", headers=HEADERS,
                           params={"wait": 30}, timeout=60).json()
    
    # 3. Descarga el resultado desde outputs[0].download_url.
    print(job["outputs"][0]["download_url"] if job["outputs"] else job["data"] or job["error"])
    // Node 18 o posterior. Guárdalo como run.mjs: el await de nivel superior necesita un módulo.
    const BASE = "https://staglight.ai/api/v1";
    const headers = { Authorization: `Bearer ${process.env.STAGLIGHT_API_KEY}` };
    
    // 1. Crea el trabajo. Se cobra una vez y se reembolsa si falla.
    let res = await fetch(`${BASE}/jobs`, {
      method: "POST",
      headers: { ...headers, "Content-Type": "application/json", "Idempotency-Key": crypto.randomUUID() },
      body: JSON.stringify({
        "op": "image.nano-banana-pro",
        "params": {
          "prompt": "Foto de producto premium de un frasco de sérum de vidrio sobre piedra mojada, luz suave de ventana",
          "aspect_ratio": "4:5"
        },
        "max_credits": 16
      }),
    });
    if (!res.ok) throw new Error((await res.json()).error.message);
    let job = await res.json();
    
    // 2. Consulta hasta que termine. Cada llamada espera hasta 30 segundos.
    while (job.status === "queued" || job.status === "running") {
      job = await (await fetch(`${BASE}/jobs/${job.id}?wait=30`, { headers })).json();
    }
    
    // 3. Descarga el resultado desde outputs[0].download_url.
    console.log(job.outputs[0]?.download_url ?? job.data ?? job.error);

    POST /api/v1/jobsjob.idGET /api/v1/jobs/{id}?wait=30download_url

  4. 04

    Síguela

    Cada tarea, cargo y reembolso aparece en tu espacio. Una tarea siempre está en uno de estos estados.

    Abrir el registro de tareas

    Estado de la tarea

    queued
    Aceptada y cobrada. Espera su turno.
    running
    El modelo está trabajando en ella.
    succeeded
    Lista. Los archivos están en outputs.
    failed
    No funcionó. Los créditos han vuelto solos.
    canceled
    Cancelada antes de empezar. Los créditos han vuelto.

Un prompt. Tu agente hace el resto.

Dale a Claude Code, Codex o Cursor el contexto para crear tu integración con Staglight. Empieza por la documentación, no por una página en blanco.

Abrir el índice de la documentación
staglight / agent.prompt
Lee la documentación de la API de Staglight:
https://staglight.ai/es/llms.txt
https://staglight.ai/es/docs/api

Crea una integración en el servidor que genere una imagen de producto
con POST /api/v1/jobs (op "image.nano-banana-pro") y que luego consulte
GET /api/v1/jobs/{id}?wait=30 hasta que el trabajo termine.

Lee la clave de la variable de entorno STAGLIGHT_API_KEY; nunca la pongas en código del navegador.
Consulta primero el saldo (GET /api/v1/me) y el precio (POST /api/v1/estimate).
Envía un Idempotency-Key con cada solicitud de pago. Si se agota el tiempo, no
reintentes a ciegas: busca antes el trabajo con GET /api/v1/jobs?idempotency_key=...
Devuelve la imagen terminada cuando su estado sea succeeded.