Generaciones

Una generación es una unidad de trabajo asíncrono: una imagen, un video, una pista de audio, un renderizado. Las herramientas con returns_generation: true inician una o más y responden de inmediato con sus ids. Sígalas mediante sondeo, mediante webhook o de ambas formas: use un webhook como señal principal y un sondeo ocasional como red de seguridad.

EstadosCopy Anchor Link

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

Trate cualquier estado que no reconozca como no final y siga la generación; pueden añadirse nuevos estados intermedios.

El objeto de generaciónCopy 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
}

Leer una generaciónCopy Anchor Link

GET /v1/direct/generations/{id} responde 200 con { "generation": { … } }.

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

• wait es opcional, de 0 a 45 segundos. La solicitud se mantiene abierta hasta que cambia el estado de la generación o esta termina, y entonces responde de inmediato.
• Cuando se agota la espera, responde con el estado actual. Un valor superior a 45 se limita a 45.
• Una generación de otra organización, o una que esta clave no puede leer, responde 404, nunca 403, para que no se puedan sondear ids ajenos.

Leer varias generacionesCopy Anchor Link

POST /v1/direct/generations/batch-get lee hasta 10 generaciones en una sola solicitud.

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

• Con wait, la solicitud responde en cuanto alguna de ellas cambia de estado o todas son finales.
• La respuesta es { "generations": [ … ], "not_found": ["…"] }, en el orden solicitado.

Con qué frecuencia sondearCopy Anchor Link

Cada inicio y cada lectura no final llevan poll_after_seconds. Espere al menos ese tiempo antes de la siguiente lectura y luego vaya espaciando las lecturas.

Un sondeo largo (wait=45) cuenta como una sola lectura por mucho que se mantenga abierto, así que es la forma más rápida y también la más barata de sondear. Configure el tiempo de espera de su cliente HTTP por encima de la espera: 60 s para 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))

Límites de sondeoCopy Anchor Link

Una lectura por lotes cuenta una vez por id en ambos límites. Con la cadencia recomendada, una clave puede seguir varios cientos de generaciones en curso a la vez; si sigue más, use webhooks.

Si tiene algún problema o alguna pregunta, no dude en ponerse en contacto con nosotros. Estaremos encantados de ayudarle. Escríbanos a support@morphic.com.