API Calendar & Images
Événements de calendrier éditorial ainsi que génération, galerie et édition d'images IA via HTTP.
Deux sous-systèmes étroitement liés : l'Editorial Calendar planifie les publications prévues par projet, l'Image Gallery gère toutes les images générées au niveau de l'équipe. Les deux travaillent avec les Articles — un événement de calendrier référence souvent un article, une image est souvent générée directement depuis un slot Hero d'article.
Contexte des modules : Editorial Calendar · Image Gallery.
Calendar
Liste d'événements propre à chaque projet, chaque event est un slot de contenu planifié (article, post social, newsletter, etc.).
| Méthode | Endpoint | Description |
|---|---|---|
| GET | /v1/projects/{project}/calendar |
Tous les events du projet |
| POST | /v1/projects/{project}/calendar |
Créer un nouvel event |
| GET | /v1/calendar/{id} |
Détail |
| PUT | /v1/calendar/{id} |
Update (title, scheduled_at, status, article_id) |
| DELETE | /v1/calendar/{id} |
Suppression |
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 par projet — conservé pour des raisons de compatibilité. Pour les nouvelles intégrations, utilise la galerie au niveau équipe ci-dessous.
| Méthode | Endpoint | Description |
|---|---|---|
| GET | /v1/projects/{project}/images |
Images d'un projet (legacy) |
Image Gallery (team-scoped, voie principale)
Les IDs cross-team renvoient 404 (pas de fuite d'existence, pas de 403).
Lecture & filtrage
| Méthode | Endpoint | Crédits | Description |
|---|---|---|---|
| GET | /v1/images |
0 | Filtres : ?q, ?model, ?from, ?to, ?favorite, ?tags[], ?sort=newest|oldest|edited, ?page, ?per_page |
| GET | /v1/images/trash |
0 | Images soft-deleted |
| GET | /v1/images/{id} |
0 | Détail incl. variants[] et arbre parent |
Génération & édition
| Méthode | Endpoint | Crédits | Description |
|---|---|---|---|
| POST | /v1/generate/image |
5 | Générer une nouvelle image à partir d'un prompt (async) |
| POST | /v1/images/{id}/edit |
10 | Variante d'édition via OpenAI /v1/images/edits. Async 202 → {job_id, edit_session_id} |
| PATCH | /v1/images/{id} |
0 | Métadonnées : {title?, tags?[]} |
| POST | /v1/images/{id}/favorite |
0 | Toggle is_favorite |
# Dispatcher un edit
curl -X POST "$BASE/images/42/edit" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"prompt":"same scene, golden hour lighting"}'
# Poller jusqu'à edit terminé — la nouvelle variante apparaît dans variants[]
curl "$BASE/images/42" -H "Authorization: Bearer $TOKEN" \
| jq '.data.variants[-1] | {id, processing_status, url}'
Trash & Bulk
| Méthode | Endpoint | Crédits | Description |
|---|---|---|---|
| DELETE | /v1/images/{id} |
0 | Soft-delete (30 jours en trash, puis hard-delete) |
| POST | /v1/images/{id}/restore |
0 | Restaurer depuis le trash |
| DELETE | /v1/images/{id}/forever |
0 | Suppression définitive — UNIQUEMENT depuis le trash, sinon 409 |
| POST | /v1/images/bulk/delete |
0 | Body {ids:[]} max 200 |
| POST | /v1/images/bulk/restore |
0 | Body {ids:[]} max 200 |
| POST | /v1/images/bulk/export |
0 | Body {ids:[]} max 500. Async 202 → {job_id} (ZIP) |
| GET | /v1/images/exports/{job_id} |
0 | Statut d'export : {status, download_url?} |
Sharing & Chat
| Méthode | Endpoint | Crédits | Description |
|---|---|---|---|
| POST | /v1/images/{id}/open-in-chat |
0 | Crée une AiChatSession avec gallery_image_id={id} → {session_id} |
| POST | /v1/images/{id}/share |
0 | Public-share idempotent. Body {expires_at?} → {token, public_url, …} |
| PATCH | /v1/images/{id}/share |
0 | Modifier l'expiry. {expires_at: ISO|null} (404 si pas de share actif) |
| DELETE | /v1/images/{id}/share |
0 | Révoquer le public share (le view-count reste) |
Notes
- Image-Generate est async.
POST /v1/generate/imagerenvoie202avec un job ID — polleGET /v1/images/{id}jusqu'àprocessing_status == "ready". - Edit produit une variante, pas un remplacement. L'original reste préservé ; la nouvelle variante est accrochée à l'arbre
parent. - Les limites bulk sont strictes.
bulk/deleteetbulk/restoresont plafonnés à 200 IDs,bulk/exportà 500. Envoie les sets plus grands par tranches. - Gallery est team-scoped. Un accès cross-team renvoie
404(par design — pas de fuite d'existence).
Voir aussi : API Articles · Calendar · Image Gallery.