Générations

Une génération est une unité de travail asynchrone : une image, une vidéo, une piste audio, un rendu. Les outils avec returns_generation: true en lancent une ou plusieurs et répondent immédiatement avec leurs identifiants. Suivez-les par sondage, par webhook, ou les deux : utilisez un webhook comme signal principal et un sondage occasionnel comme filet de sécurité.

StatutsCopy Anchor Link

queued ──► in_progress ──► succeeded
   │             │
   │             ├──────► failed
   └─────────────┴──────► cancelled

Considérez tout statut que vous ne reconnaissez pas comme non final et continuez à suivre la génération ; de nouveaux statuts intermédiaires peuvent être ajoutés.

L’objet générationCopy Anchor Link

{
  "object": "generation",
  "id": "0192a7b3-a1c4-7e02-8f9d-1a2b3c4d5e6f",
  "tool": "generate_video",
  "status": "succeeded",
  "project_id": "01928f4e-5b7c-7d2a-9e11-3c4b5a6d7e8f",
  "model_id": "mdl_7rk2pq9vxa4m",
  "created_at": "2026-10-25T09:14:03.120Z",
  "completed_at": "2026-10-25T09:15:41.902Z",
  "error": null,
  "billing": {
    "estimated_credits": 120,
    "credits_charged": 96,
    "credits_refunded": 0,
    "credits_are_final": true,
    "credits_settle_on_output_duration": true
  },
  "assets": [
    {
      "id": "0192a7b4-0f1e-7d3c-9b8a-7c6d5e4f3a2b",
      "type": "video",
      "name": "Bicycle hero shot",
      "mime_type": "video/mp4",
      "width": 1920,
      "height": 1080,
      "duration_seconds": 8,
      "url": "https://mcp.morphic.com/m/Xk29dPq",
      "url_expires_at": null,
      "studio_url": "https://studio.morphic.com/…",
      "final_generation_expires_at": null
    }
  ],
  "content_left_out": [],
  "render_warnings": [],
  "metadata": { "order_id": "4411" },
  "poll_after_seconds": null
}

Lire une générationCopy Anchor Link

GET /v1/direct/generations/{id} répond 200 avec { "generation": { … } }.

curl -s "https://mcp.morphic.com/v1/direct/generations/$ID?wait=45" \
  -H "Authorization: Bearer $MORPHIC_API_KEY"

• wait est facultatif, de 0 à 45 secondes. La requête reste ouverte jusqu’à ce que le statut de la génération change ou qu’elle se termine, puis répond immédiatement.
• Lorsque l’attente arrive à son terme, elle répond avec l’état actuel. Une valeur supérieure à 45 est ramenée à 45.
• Une génération d’une autre organisation, ou que cette clé n’a pas le droit de lire, répond 404, jamais 403, pour que les identifiants ne puissent pas être sondés.

Lire plusieurs générationsCopy Anchor Link

POST /v1/direct/generations/batch-get lit jusqu’à 10 générations en une seule requête.

curl -s https://mcp.morphic.com/v1/direct/generations/batch-get \
  -H "Authorization: Bearer $MORPHIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["0192a7b3-…", "0192a7b3-…"], "wait": 30}'

• Avec wait, la requête répond dès que l’une d’elles change de statut ou que toutes sont finales.
• La réponse est { "generations": [ … ], "not_found": ["…"] }, dans l’ordre demandé.

À quel rythme interrogerCopy Anchor Link

Chaque lancement et chaque lecture non finale portent poll_after_seconds. Attendez au moins ce délai avant la lecture suivante, puis espacez progressivement.

Un long-polling (wait=45) compte pour une seule lecture, quelle que soit la durée pendant laquelle il est maintenu : c’est donc la façon la plus rapide et la moins coûteuse d’interroger. Réglez le délai d’expiration de votre client HTTP au-dessus de l’attente : 60 s pour wait=45.

import time, requests

def wait_for(generation_id, key):
    headers = {"Authorization": f"Bearer {key}"}
    url = f"https://mcp.morphic.com/v1/direct/generations/{generation_id}"
    while True:
        r = requests.get(url, params={"wait": 45}, headers=headers, timeout=60)
        if r.status_code == 429:
            time.sleep(int(r.headers.get("Retry-After", "5")))
            continue
        r.raise_for_status()
        gen = r.json()["generation"]
        if gen["status"] in ("succeeded", "failed", "cancelled"):
            return gen
        # A long-poll already waited; only sleep if the server asks for more.
        time.sleep(max(0, (gen.get("poll_after_seconds") or 0) - 45))

Limites de sondageCopy Anchor Link

Une lecture groupée compte une fois par identifiant au regard des deux limites. Au rythme recommandé, une clé peut suivre plusieurs centaines de générations en cours simultanément ; si vous en suivez davantage, utilisez les webhooks.

Si vous rencontrez le moindre problème ou si vous avez des questions, n’hésitez pas à nous contacter. Nous serons ravis de vous aider. Écrivez-nous à support@morphic.com.