# 02 · Configurar las API keys

El editor habla con cuatro servicios externos. Cada uno pide su propia API key.
Tres son obligatorias (imágenes/video, voz, música) y una es opcional (un respaldo
de imágenes con Gemini). Las keys nunca van escritas en el código: el editor las
lee en el momento de usarlas, primero desde una variable de entorno y, si no la
encuentra, desde el Keychain de macOS.

Cuando termines, corré `npm run check` para confirmar que todo quedó en su lugar.

---

## Qué key necesita cada cosa

| Referencia | Servicio | Para qué se usa | ¿Obligatoria? | Dónde sacarla |
|---|---|---|---|---|
| `kie` | Kie.ai | Imágenes (GPT Image) y animación de video I2V (Grok) | Sí | https://kie.ai |
| `elevenlabs` | ElevenLabs | Voz (text-to-speech) y efectos de sonido | Sí | https://elevenlabs.io |
| `suno` | Suno (vía sunoapi.org) | Música de fondo instrumental | Sí | https://sunoapi.org |
| `gemini` | Google Gemini | Respaldo opcional de imágenes | No | https://aistudio.google.com/app/apikey |

La columna **Referencia** es el nombre interno que usa el código (`getKey("kie")`,
`getKey("elevenlabs")`, etc.). Lo vas a ver en los mensajes de error y en el
resultado de `npm run check`.

---

## Cómo decide el editor de dónde leer la key

Para cada key, el orden de resolución es:

1. **Variable de entorno** (por ejemplo `KIE_API_KEY`). Sirve en cualquier sistema
   (macOS, Linux, Windows) y es la forma habitual en servidores y CI.
2. **Keychain de macOS** (`security find-generic-password`). Almacenamiento local
   seguro en Mac. Solo se consulta en macOS; en otros sistemas este paso se omite
   y se usa solamente la variable de entorno.

Si la variable de entorno está definida y no está vacía, gana. Si no, el editor
busca la entrada en el Keychain. Si tampoco está, el comando falla con un mensaje
que te dice exactamente cómo configurarla.

Tenés dos formas de guardar las keys. Elegí una:

- **Opción A — Keychain de macOS.** Recomendada si trabajás en Mac. La key queda
  guardada en el llavero del sistema, fuera del repo.
- **Opción B — Archivo `.env`.** Sirve en cualquier sistema. Las keys quedan en un
  archivo local que está en `.gitignore` y nunca se sube a git.

---

## Paso 1 · Conseguir cada key

### Kie.ai (`kie`) — imágenes y video

1. Entrá a https://kie.ai y creá una cuenta o iniciá sesión.
2. Abrí la sección de API / API Keys de tu panel.
3. Generá una key y copiala.
4. Cargá créditos: el editor consume créditos de Kie por imagen y por clip de video.

### ElevenLabs (`elevenlabs`) — voz y efectos

1. Entrá a https://elevenlabs.io e iniciá sesión.
2. En tu perfil, abrí la sección de API Keys.
3. Creá una key y copiala.
4. Mientras estás ahí, copiá también un `voice_id` de una voz en español desde tu
   panel de voces. Lo vas a necesitar al generar la voz (ver `docs/03-crear-primer-video.md`).

### Suno vía sunoapi.org (`suno`) — música

1. Entrá a https://sunoapi.org y creá tu cuenta.
2. Generá tu API key desde el panel.
3. Copiala. Esta es la key de sunoapi.org, no la de la app oficial de Suno.

### Google Gemini (`gemini`) — opcional

Solo si querés un respaldo para generar imágenes. Podés saltearla.

1. Entrá a https://aistudio.google.com/app/apikey con tu cuenta de Google.
2. Creá una API key y copiala.

---

## Opción A · Guardar las keys en el Keychain de macOS

Usá `security add-generic-password`. El flag `-w` sin valor hace que el comando
te pida la key de forma interactiva: la escribís (o pegás) y queda en el Keychain,
no en el historial de la terminal.

Una entrada por servicio, con su cuenta y nombre de servicio:

| Referencia | Cuenta (`-a`) | Servicio (`-s`) |
|---|---|---|
| `kie` | `editor` | `editor:kie-ai-key` |
| `elevenlabs` | `editor` | `editor:elevenlabs-key` |
| `suno` | `editor` | `editor:sunoapi-org-key` |
| `gemini` | `editor` | `editor:gemini-key` |

Comandos (uno por key; te va a pedir el valor al ejecutarlo):

```bash
# Kie.ai
security add-generic-password -a editor -s "editor:kie-ai-key" -w

# ElevenLabs
security add-generic-password -a editor -s "editor:elevenlabs-key" -w

# Suno (sunoapi.org)
security add-generic-password -a editor -s "editor:sunoapi-org-key" -w

# Gemini (opcional)
security add-generic-password -a editor -s "editor:gemini-key" -w
```

Notas:

- Si una key ya existe y querés reemplazarla, agregá `-U` para actualizarla:
  `security add-generic-password -U -a editor -s "editor:kie-ai-key" -w`.
- Para borrar una entrada:
  `security delete-generic-password -a editor -s "editor:kie-ai-key"`.

Con esta opción no necesitás archivo `.env`.

---

## Opción B · Guardar las keys en un archivo `.env`

Sirve en cualquier sistema (macOS, Linux, Windows) y requiere Node.js 20.6 o
superior para el flag `--env-file`.

1. Copiá la plantilla (que no tiene secretos) a tu propio `.env`:

   ```bash
   cp .env.example .env
   ```

2. Abrí `.env` y pegá tus keys después del signo `=`, sin comillas y sin espacios:

   ```
   KIE_API_KEY=tu-key-de-kie
   ELEVENLABS_API_KEY=tu-key-de-elevenlabs
   SUNO_API_KEY=tu-key-de-suno
   GEMINI_API_KEY=tu-key-de-gemini   # opcional, podés dejarlo vacío
   ```

3. Pasá el archivo a Node con `--env-file=.env` en cada comando. Por ejemplo:

   ```bash
   node --env-file=.env src/runners/imagen.mjs --prompt "..." --out salida.png
   ```

El archivo `.env` ya está listado en `.gitignore`, así que no se sube a git.

> Si definís una variable de entorno por otra vía (por ejemplo `export
> KIE_API_KEY=...` en tu shell), esa toma precedencia sobre el Keychain igual que
> el `.env`. Es el mismo paso 1 del orden de resolución.

---

## Las keys nunca van al código ni a git

- No escribas keys dentro de archivos `.mjs`, ni en este `docs/`, ni en ningún
  markdown del repo.
- Las keys solo pueden venir de dos lugares: una variable de entorno (incluido
  `.env`) o el Keychain de macOS.
- `.gitignore` ya excluye `.env`, `.env.local` y `*.key`. Antes de un commit,
  revisá que no estés agregando ninguna key por error (por ejemplo con
  `git status` y `git diff --staged`).
- El editor lee las keys en memoria y las usa para llamar a cada servicio; no las
  imprime ni las guarda en disco. El verificador (`npm run check`) tampoco muestra
  el valor de ninguna key: solo dice si está configurada o no.

---

## Paso final · Verificar

Corré el verificador desde la raíz del repo:

```bash
npm run check
```

Vas a ver dos bloques:

- **Herramientas**: Node.js, ffmpeg, ffprobe y npx.
- **API keys**: una línea por referencia (`kie`, `elevenlabs`, `suno`, `gemini`),
  con su estado. `gemini` se marca como opcional, así que si falta no cuenta como
  error.

Si guardaste las keys en un `.env` (Opción B), el `npm run check` por sí solo no
las carga. Corré el verificador pasándole el archivo:

```bash
node --env-file=.env scripts/check-setup.mjs
```

Cuando todas las keys obligatorias estén en verde, seguí con
`docs/03-crear-primer-video.md`.

### Si una key sale en rojo

- Revisá que el nombre del servicio en el Keychain sea exactamente el de la tabla
  (Opción A), o el nombre de la variable en `.env` (Opción B).
- En el Keychain, confirmá que usaste la cuenta `editor`.
- Si usás `.env`, confirmá que estás corriendo con `node --env-file=.env`.
- Recordá que el Keychain solo se consulta en macOS; en Linux o Windows usá la
  Opción B.
