Generate an AI Image with Magic Hour and Wait for Completion

id: magic-hour-ai-image-generation
namespace: company.team
description: |
  Create an AI image with Magic Hour, retain the returned project ID, poll that same
  project until it completes or fails, and expose the final download URL without
  accidentally starting duplicate billable renders.

inputs:
  - id: prompt
    type: STRING
    displayName: Image prompt
    description: A detailed description of the image to generate.
    required: true
    defaults: A ceramic coffee mug on a warm studio background, premium product
      photography

  - id: aspect_ratio
    type: SELECT
    displayName: Aspect ratio
    description: Output image aspect ratio supported by the Magic Hour image generator.
    required: true
    values:
      - "1:1"
      - "16:9"
      - "9:16"
    defaults: "1:1"

tasks:
  - id: create_image
    type: io.kestra.plugin.core.http.Request
    description: Start exactly one Magic Hour image project and retain its ID for
      every later poll.
    uri: https://api.magichour.ai/v1/ai-image-generator
    method: POST
    contentType: application/json
    headers:
      Authorization: "Bearer {{ secret('MAGIC_HOUR_API_KEY') }}"
      Accept: application/json
    body: |
      {
        "name": "Kestra image {{ execution.id }}",
        "image_count": 1,
        "model": "default",
        "aspect_ratio": "{{ inputs.aspect_ratio }}",
        "resolution": "auto",
        "style": {
          "prompt": {{ inputs.prompt | toJson }},
          "tool": "general"
        }
      }

  - id: wait_for_image
    type: io.kestra.plugin.core.flow.LoopUntil
    description: Poll the original project every 10 seconds until Magic Hour reports
      complete or error.
    condition: "{{ ['complete', 'error'] contains (outputs.poll_project.body |
      jq('.status') | first) }}"
    checkFrequency:
      interval: PT10S
      maxDuration: PT10M
    failOnMaxReached: true
    tasks:
      - id: poll_project
        type: io.kestra.plugin.core.http.Request
        description: Retrieve status and downloads for the project created by create_image.
        uri: "https://api.magichour.ai/v1/image-projects/{{ outputs.create_image.body |
          jq('.id') | first }}"
        method: GET
        headers:
          Authorization: "Bearer {{ secret('MAGIC_HOUR_API_KEY') }}"
          Accept: application/json

  - id: fail_render_error
    type: io.kestra.plugin.core.flow.If
    description: Fail explicitly when Magic Hour reaches a terminal error state.
    condition: "{{ (outputs.poll_project.body | jq('.status') | first) == 'error' }}"
    then:
      - id: report_render_error
        type: io.kestra.plugin.core.execution.Fail
        errorMessage: "Magic Hour project {{ outputs.create_image.body | jq('.id') |
          first }} failed: {{ outputs.poll_project.body | jq('.error') | first
          }}"

  - id: report_completed_image
    type: io.kestra.plugin.core.log.Log
    description: Report the completed project ID and exact expiring download URL.
    message: |
      Magic Hour project: {{ outputs.create_image.body | jq('.id') | first }}
      Download URL: {{ outputs.poll_project.body | jq('.downloads[0].url') | first }}
      Expires at: {{ outputs.poll_project.body | jq('.downloads[0].expires_at') | first }}