API Calendar e Images
Eventos de Editorial Calendar y AI Image Generation, gallery y edits por HTTP.
Dos subsistemas estrechamente relacionados: el Editorial Calendar planifica publicaciones programadas por proyecto; la Image Gallery gestiona, a nivel team, todas las imágenes generadas. Ambos colaboran con artículos — un evento del calendar suele referenciar un artículo y una imagen suele generarse directamente desde el slot hero del artículo.
Contexto del módulo: Editorial Calendar · Image Gallery.
Calendar
Una lista de eventos por proyecto; cada evento es un slot de contenido programado (artículo, post social, newsletter, etc.).
| Method | Endpoint | Descripción |
|---|---|---|
| GET | /v1/projects/{project}/calendar |
Todos los eventos del proyecto |
| POST | /v1/projects/{project}/calendar |
Crear evento |
| GET | /v1/calendar/{id} |
Detalle |
| PUT | /v1/calendar/{id} |
Update (title, scheduled_at, status, article_id) |
| DELETE | /v1/calendar/{id} |
Eliminar |
curl -X POST "$BASE/projects/12/calendar" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{
"title": "AI Coding Tools — Launch-Post",
"scheduled_at": "2026-05-15T09:00:00Z",
"article_id": 88,
"status": "scheduled"
}'
Project Images (legacy)
Listing por proyecto — se mantiene por compatibilidad. Para integraciones nuevas, usa la gallery a nivel team de abajo.
| Method | Endpoint | Descripción |
|---|---|---|
| GET | /v1/projects/{project}/images |
Imágenes de un proyecto (legacy) |
Image Gallery (team-scoped, vía principal)
Los IDs cross-team responden 404 (sin fuga de existencia, no 403).
Lectura y filtrado
| Method | Endpoint | Créditos | Descripción |
|---|---|---|---|
| GET | /v1/images |
0 | Filtros: ?q, ?model, ?from, ?to, ?favorite, ?tags[], ?sort=newest|oldest|edited, ?page, ?per_page |
| GET | /v1/images/trash |
0 | Imágenes soft-deleted |
| GET | /v1/images/{id} |
0 | Detalle con variants[] y árbol parent |
Generar y editar
| Method | Endpoint | Créditos | Descripción |
|---|---|---|---|
| POST | /v1/generate/image |
5 | Generar nueva imagen desde prompt (async) |
| POST | /v1/images/{id}/edit |
10 | Variante editada vía OpenAI /v1/images/edits. Async 202 → {job_id, edit_session_id} |
| PATCH | /v1/images/{id} |
0 | Metadatos: {title?, tags?[]} |
| POST | /v1/images/{id}/favorite |
0 | Toggle is_favorite |
# Dispatchar edit
curl -X POST "$BASE/images/42/edit" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"prompt":"same scene, golden hour lighting"}'
# Polling hasta que el edit termine — la nueva variante aparece en variants[]
curl "$BASE/images/42" -H "Authorization: Bearer $TOKEN" \
| jq '.data.variants[-1] | {id, processing_status, url}'
Trash y bulk
| Method | Endpoint | Créditos | Descripción |
|---|---|---|---|
| DELETE | /v1/images/{id} |
0 | Soft-delete (30 días en trash, luego hard-delete) |
| POST | /v1/images/{id}/restore |
0 | Restaurar desde trash |
| DELETE | /v1/images/{id}/forever |
0 | Borrar definitivamente — SOLO desde trash, si no 409 |
| POST | /v1/images/bulk/delete |
0 | Body {ids:[]} máx 200 |
| POST | /v1/images/bulk/restore |
0 | Body {ids:[]} máx 200 |
| POST | /v1/images/bulk/export |
0 | Body {ids:[]} máx 500. Async 202 → {job_id} (ZIP) |
| GET | /v1/images/exports/{job_id} |
0 | Status del export: {status, download_url?} |
Sharing y chat
| Method | Endpoint | Créditos | Descripción |
|---|---|---|---|
| POST | /v1/images/{id}/open-in-chat |
0 | Crea AiChatSession con gallery_image_id={id} → {session_id} |
| POST | /v1/images/{id}/share |
0 | Public share idempotente. Body {expires_at?} → {token, public_url, …} |
| PATCH | /v1/images/{id}/share |
0 | Cambiar expiry. {expires_at: ISO|null} (404 si no hay share activo) |
| DELETE | /v1/images/{id}/share |
0 | Revocar public share (el view count se mantiene) |
Notas
- Image generate es async.
POST /v1/generate/imagedevuelve202con job ID — haz polling aGET /v1/images/{id}hastaprocessing_status == "ready". - Edit crea variante, no reemplaza. El original queda intacto; la nueva variante cuelga del árbol
parent. - Los límites bulk son duros.
bulk/deleteybulk/restoreestán topeados a 200 IDs,bulk/exporta 500. Sets más grandes en tandas. - La gallery está scope al team. El acceso cross-team responde
404(por diseño — sin fuga de existencia).
Relacionado: API de Artículos · Calendar · Image Gallery.