Generasi

Generasi adalah satu unit pekerjaan asinkron: satu gambar, satu video, satu trek audio, satu render. Alat dengan returns_generation: true memulai satu atau beberapa generasi dan langsung menjawab dengan id-nya. Pantau generasi dengan polling, dengan webhook, atau keduanya: gunakan webhook sebagai sinyal utama dan polling sesekali sebagai jaring pengaman.

StatusCopy Anchor Link

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

Anggap status apa pun yang tidak Anda kenali sebagai belum final dan teruslah memantau generasi itu; status perantara baru dapat ditambahkan.

Objek generasiCopy 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
}

Membaca satu generasiCopy Anchor Link

GET /v1/direct/generations/{id} menjawab 200 dengan { "generation": { … } }.

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

• wait bersifat opsional, 0 hingga 45 detik. Permintaan ditahan terbuka sampai status generasi berubah atau generasi selesai, lalu langsung dijawab.
• Jika waktu tunggu habis, permintaan dijawab dengan status saat itu. Nilai di atas 45 dibatasi menjadi 45.
• Generasi milik organisasi lain, atau yang tidak boleh dibaca kunci ini, dijawab dengan 404, tidak pernah 403, sehingga id tidak dapat ditebak-tebak.

Membaca beberapa generasiCopy Anchor Link

POST /v1/direct/generations/batch-get membaca hingga 10 generasi dalam satu permintaan.

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

• Dengan wait, permintaan dijawab begitu salah satunya berubah status atau semuanya sudah final.
• Responsnya adalah { "generations": [ … ], "not_found": ["…"] }, sesuai urutan yang diminta.

Seberapa sering melakukan pollingCopy Anchor Link

Setiap permulaan dan setiap pembacaan yang belum final membawa poll_after_seconds. Tunggu setidaknya selama itu sebelum pembacaan berikutnya, lalu perlambat secara bertahap.

Long-poll (wait=45) dihitung sebagai satu pembacaan berapa pun lamanya ditahan, sehingga ini cara polling yang paling cepat sekaligus paling hemat. Atur timeout klien HTTP Anda di atas waktu tunggu: 60 dtk untuk 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))

Batas pollingCopy Anchor Link

Pembacaan batch dihitung sekali per id terhadap kedua batas. Dengan ritme yang disarankan, satu kunci dapat memantau beberapa ratus generasi yang sedang berjalan sekaligus; jika Anda memantau lebih banyak, gunakan webhook.

Jika Anda mengalami kendala atau memiliki pertanyaan, jangan ragu untuk menghubungi kami. Kami dengan senang hati akan membantu. Tulis kepada kami di support@morphic.com.