Generierungen

Eine Generierung ist eine asynchrone Arbeitseinheit: ein Bild, ein Video, eine Audiospur, ein Render. Tools mit returns_generation: true starten eine oder mehrere davon und antworten sofort mit ihren IDs. Verfolgen Sie sie per Polling, per Webhook oder beidem: Nutzen Sie einen Webhook als Hauptsignal und eine gelegentliche Abfrage als Sicherheitsnetz.

StatusCopy Anchor Link

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

Behandeln Sie jeden Status, den Sie nicht kennen, als nicht endgültig und verfolgen Sie die Generierung weiter; neue Zwischenstatus können hinzukommen.

Das GenerierungsobjektCopy 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
}

Eine Generierung lesenCopy Anchor Link

GET /v1/direct/generations/{id} antwortet mit 200 und { "generation": { … } }.

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

• wait ist optional, 0 bis 45 Sekunden. Die Anfrage wird offen gehalten, bis sich der Status der Generierung ändert oder sie abgeschlossen ist, und antwortet dann sofort.
• Läuft die Wartezeit ab, antwortet sie mit dem aktuellen Stand. Ein Wert über 45 wird auf 45 begrenzt.
• Eine Generierung einer anderen Organisation oder eine, die dieser Schlüssel nicht lesen darf, antwortet mit 404, nie mit 403, sodass sich IDs nicht ausprobieren lassen.

Mehrere Generierungen lesenCopy Anchor Link

POST /v1/direct/generations/batch-get liest bis zu 10 Generierungen in einer Anfrage.

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}'

• Mit wait antwortet die Anfrage, sobald eine davon ihren Status ändert oder alle endgültig sind.
• Die Antwort lautet { "generations": [ … ], "not_found": ["…"] }, in der angefragten Reihenfolge.

Wie oft Sie abfragen solltenCopy Anchor Link

Jeder Start und jedes nicht endgültige Lesen enthält poll_after_seconds. Warten Sie mindestens so lange bis zur nächsten Abfrage und verlängern Sie die Abstände danach schrittweise.

Ein Long-Poll (wait=45) zählt als eine einzige Abfrage, egal wie lange er offen gehalten wird. Er ist daher sowohl die schnellste als auch die günstigste Art abzufragen. Setzen Sie das Timeout Ihres HTTP-Clients über die Wartezeit: 60 s für 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))

Polling-LimitsCopy Anchor Link

Ein gebündeltes Lesen zählt gegen beide Limits einmal pro ID. Im empfohlenen Rhythmus kann ein Schlüssel mehrere Hundert laufende Generierungen gleichzeitig verfolgen; wenn Sie mehr verfolgen, nutzen Sie Webhooks.

Wenn Sie Probleme haben oder Fragen haben, können Sie sich gerne an uns wenden. Wir helfen Ihnen gerne. Schreiben Sie uns an support@morphic.com.