Gerações

Uma geração é uma unidade de trabalho assíncrono: uma imagem, um vídeo, uma faixa de áudio, uma renderização. As ferramentas com returns_generation: true iniciam uma ou mais e respondem na hora com os IDs delas. Acompanhe-as por polling, por webhook ou pelos dois: use um webhook como sinal principal e uma consulta ocasional como rede de segurança.

StatusCopy Anchor Link

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

Trate qualquer status que você não reconheça como não final e continue acompanhando a geração; novos status intermediários podem ser adicionados.

O objeto de geraçãoCopy 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
}

Ler uma geraçãoCopy Anchor Link

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

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

• wait é opcional, de 0 a 45 segundos. A solicitação fica aberta até o status da geração mudar ou ela terminar, e então responde na hora.
• Quando a espera se esgota, ela responde com o estado atual. Um valor acima de 45 é reduzido para 45.
• Uma geração de outra organização, ou uma que esta chave não pode ler, responde 404, nunca 403, para que IDs não possam ser sondados.

Ler várias geraçõesCopy Anchor Link

POST /v1/direct/generations/batch-get lê até 10 gerações em uma única solicitação.

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

• Com wait, a solicitação responde assim que qualquer uma delas mudar de status ou todas forem finais.
• A resposta é { "generations": [ … ], "not_found": ["…"] }, na ordem pedida.

Com que frequência consultarCopy Anchor Link

Cada início e cada leitura não final trazem poll_after_seconds. Espere pelo menos esse tempo antes da próxima leitura e depois vá espaçando as consultas.

Um long-poll (wait=45) custa uma leitura, não importa quanto tempo fique aberto, então é a forma mais rápida e mais barata de consultar. Configure o timeout do seu cliente HTTP acima da 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))

Limites de pollingCopy Anchor Link

Uma leitura em lote conta uma vez por ID nos dois limites. No ritmo recomendado, uma chave consegue acompanhar várias centenas de gerações em andamento ao mesmo tempo; se você acompanhar mais, use webhooks.

Se você tiver algum problema ou alguma dúvida, entre em contato. Teremos prazer em ajudar. Escreva para nós em support@morphic.com.