openapi: 3.2.0
info:
  title: Ludo Ai Videos API
  version: 0.9.10
  x-logo:
    url: /static/logo-small.png
    altText: Logo
  x-refined-note:
  - x-model-lineup differs across the merged source definitions and was not carried
  description: 'Operations tagged Videos across 2 of this provider''s published API definitions: ludo-ai-rest-api-openapi.yml, ludo-ai-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: /api
tags:
- name: Videos
paths:
  /assets/video:
    post:
      summary: createVideo
      tags:
      - Videos
      operationId: createVideo
      x-credit-action: GENERATE_VIDEO
      security:
      - ApiKey: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateVideoPayloadPublic'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoResult'
        '202':
          description: 'Accepted - the generation was queued; poll GET /assets/jobs/{id}. A synchronous (async: false) call still running after 15 minutes also receives this.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicJob'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-codeSamples:
      - lang: Shell
        label: cURL
        source: "curl -X POST \"https://api.ludo.ai/api/assets/video\" \\\n  -H \"Authorization: ApiKey YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"image\":\"<url> OR data:image/png;base64,...\",\"prompt\":\"string\"}'"
      - lang: JavaScript
        label: JavaScript
        source: "const response = await fetch(\"https://api.ludo.ai/api/assets/video\", {\n  method: \"POST\",\n  headers: {\n    \"Authorization\": \"ApiKey YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"image\": \"<url> OR data:image/png;base64,...\",\n    \"prompt\": \"string\"\n  })\n});\n\nconst data = await response.json();\nconsole.log(data);"
      - lang: Python
        label: Python
        source: "import requests\n\nresponse = requests.post(\n    \"https://api.ludo.ai/api/assets/video\",\n    headers={\n        \"Authorization\": \"ApiKey YOUR_API_KEY\",\n        \"Content-Type\": \"application/json\"\n    },\n    json={\n      \"image\": \"<url> OR data:image/png;base64,...\",\n      \"prompt\": \"string\"\n    }\n)\n\nprint(response.json())"
      x-credit-description: 'This endpoint''s credit cost varies by model and duration (credits/s × seconds, rounded to 0.1; a model''s minimum charge applies when that product is lower). Available models: Griffin (1.5 credits/s, shortest duration 5s, so 7.5 credits minimum; 5s = 7.5, 6s = 9, 7s = 10.5, 8s = 12, 9s = 13.5, 10s = 15, 11s = 16.5, 12s = 18, 13s = 19.5, 14s = 21, 15s = 22.5) · Griffin HD (2 credits/s, shortest duration 5s, so 10 credits minimum; 5s = 10, 6s = 12, 7s = 14, 8s = 16, 9s = 18, 10s = 20, 11s = 22, 12s = 24, 13s = 26, 14s = 28, 15s = 30) · Blitz (1 credits/s, shortest duration 2s, so 2 credits minimum; 2s = 2, 3s = 3, 4s = 4, 5s = 5, 6s = 6, 7s = 7, 8s = 8, 9s = 9, 10s = 10, 11s = 11, 12s = 12) - LEGACY - scheduled for removal, do not use for new work · Eagle (1.3 credits/s; 1s = 1.3, 2s = 2.6, 3s = 3.9, 4s = 5.2, 5s = 6.5, 6s = 7.8, 7s = 9.1, 8s = 10.4, 9s = 11.7, 10s = 13, 11s = 14.3, 12s = 15.6, 13s = 16.9, 14s = 18.2, 15s = 19.5) - LEGACY - scheduled for removal, do not use for new work · Eagle with Audio (1.8 credits/s; 1s = 1.8, 2s = 3.6, 3s = 5.4, 4s = 7.2, 5s = 9, 6s = 10.8, 7s = 12.6, 8s = 14.4, 9s = 16.2, 10s = 18, 11s = 19.8, 12s = 21.6, 13s = 23.4, 14s = 25.2, 15s = 27) - LEGACY - scheduled for removal, do not use for new work'
      x-credit-summary: 'credits/s × seconds, per model: Griffin 1.5/s (shortest duration 5s, so 7.5 credits minimum), Griffin HD 2/s (shortest duration 5s, so 10 credits minimum), Blitz 1/s (shortest duration 2s, so 2 credits minimum) [LEGACY], Eagle 1.3/s [LEGACY], Eagle with Audio 1.8/s [LEGACY]; [LEGACY] models are scheduled for removal - do not use them for new work; see this endpoint''s full pricing table in the API docs'
      description: 'Generate a short video clip from a source image and a motion text prompt (image-to-video); a source `image` is required - to make a video from text alone, first createImage and animate that, or use createVideoFromReferences with reference images. Griffin (default, 480p) and Griffin HD (720p) both generate a soundtrack; no separate audio step is needed. The job result is the video URL and its actual duration in seconds. Optionally pass `final_image` to interpolate between a start and end frame. The chosen `model` and `duration` must be compatible (incompatible combinations return HTTP 400); see the `model` and `duration` fields for the values each model accepts. Credits are held when the job is accepted; the final charge is max(rate × produced seconds, the model''s minimum charge), never more than for the duration you requested, and the difference (or everything, if the job fails or is cancelled) is refunded. Pass an optional `request_id` to tag the result so you can locate it later via listGenerations (type video). Related tools: use `createImage` for static images, `animateSprite` for sprite-sheet animation, and listGenerations (type video) to list videos you generated earlier. Requires an API key (user scope). The call returns 202 with a job id - poll getApiJob (pass wait 30 to long-poll) honouring poll_after_ms, until status is succeeded; its result field is exactly the response documented for this operation. Synchronous responses are deprecated but still supported: pass `async: false` to block until the result is ready and receive it as the response body. Synchronous calls run on the same queue: the response carries an X-Ludo-Job-Id header, and a job still running after 15 minutes comes back as 202 with the job instead of an error. Each account may have up to 50 generations queued or running at once via the API; a request beyond that returns 429 (code PENDING_JOBS_LIMIT).


        > **Credits:** This endpoint''s credit cost varies by model and duration (credits/s × seconds, rounded to 0.1; a model''s minimum charge applies when that product is lower). Available models: Griffin (1.5 credits/s, shortest duration 5s, so 7.5 credits minimum; 5s = 7.5, 6s = 9, 7s = 10.5, 8s = 12, 9s = 13.5, 10s = 15, 11s = 16.5, 12s = 18, 13s = 19.5, 14s = 21, 15s = 22.5) · Griffin HD (2 credits/s, shortest duration 5s, so 10 credits minimum; 5s = 10, 6s = 12, 7s = 14, 8s = 16, 9s = 18, 10s = 20, 11s = 22, 12s = 24, 13s = 26, 14s = 28, 15s = 30) · Blitz (1 credits/s, shortest duration 2s, so 2 credits minimum; 2s = 2, 3s = 3, 4s = 4, 5s = 5, 6s = 6, 7s = 7, 8s = 8, 9s = 9, 10s = 10, 11s = 11, 12s = 12) - LEGACY - scheduled for removal, do not use for new work · Eagle (1.3 credits/s; 1s = 1.3, 2s = 2.6, 3s = 3.9, 4s = 5.2, 5s = 6.5, 6s = 7.8, 7s = 9.1, 8s = 10.4, 9s = 11.7, 10s = 13, 11s = 14.3, 12s = 15.6, 13s = 16.9, 14s = 18.2, 15s = 19.5) - LEGACY - scheduled for removal, do not use for new work · Eagle with Audio (1.8 credits/s; 1s = 1.8, 2s = 3.6, 3s = 5.4, 4s = 7.2, 5s = 9, 6s = 10.8, 7s = 12.6, 8s = 14.4, 9s = 16.2, 10s = 18, 11s = 19.8, 12s = 21.6, 13s = 23.4, 14s = 25.2, 15s = 27) - LEGACY - scheduled for removal, do not use for new work.'
      x-mcp-description: 'Generate a short video clip from a source image and a motion text prompt (image-to-video); a source `image` is required - to make a video from text alone, first createImage and animate that, or use createVideoFromReferences with reference images. Griffin (default, 480p) and Griffin HD (720p) both generate a soundtrack; no separate audio step is needed. The job result is the video URL and its actual duration in seconds. Optionally pass `final_image` to interpolate between a start and end frame. The chosen `model` and `duration` must be compatible (incompatible combinations return HTTP 400); see the `model` and `duration` fields for the values each model accepts. Credits are held when the job is accepted; the final charge is max(rate × produced seconds, the model''s minimum charge), never more than for the duration you requested, and the difference (or everything, if the job fails or is cancelled) is refunded. Pass an optional `request_id` to tag the result so you can locate it later via listGenerations (type video). Related tools: use `createImage` for static images, `animateSprite` for sprite-sheet animation, and listGenerations (type video) to list videos you generated earlier. Requires an API key (user scope). The call returns 202 with a job id - poll getApiJob (pass wait 30 to long-poll) honouring poll_after_ms, until status is succeeded; its result field is exactly the response documented for this operation. Synchronous responses are deprecated but still supported: pass `async: false` to block until the result is ready and receive it as the response body. Synchronous calls run on the same queue: the response carries an X-Ludo-Job-Id header, and a job still running after 15 minutes comes back as 202 with the job instead of an error. Each account may have up to 50 generations queued or running at once via the API; a request beyond that returns 429 (code PENDING_JOBS_LIMIT).


        Credits: credits/s × seconds, per model: Griffin 1.5/s (shortest duration 5s, so 7.5 credits minimum), Griffin HD 2/s (shortest duration 5s, so 10 credits minimum), Blitz 1/s (shortest duration 2s, so 2 credits minimum) [LEGACY], Eagle 1.3/s [LEGACY], Eagle with Audio 1.8/s [LEGACY]; [LEGACY] models are scheduled for removal - do not use them for new work; see this endpoint''s full pricing table in the API docs.'
    servers:
    - url: /api
  /assets/video/references:
    post:
      summary: createVideoFromReferences
      tags:
      - Videos
      operationId: createVideoFromReferences
      x-credit-action: REFERENCES_TO_VIDEO
      security:
      - ApiKey: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReferencesToVideoPayloadPublic'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoResult'
        '202':
          description: 'Accepted - the generation was queued; poll GET /assets/jobs/{id}. A synchronous (async: false) call still running after 15 minutes also receives this.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicJob'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-codeSamples:
      - lang: Shell
        label: cURL
        source: "curl -X POST \"https://api.ludo.ai/api/assets/video/references\" \\\n  -H \"Authorization: ApiKey YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"prompt\":\"string\",\"images\":[\"string\"]}'"
      - lang: JavaScript
        label: JavaScript
        source: "const response = await fetch(\"https://api.ludo.ai/api/assets/video/references\", {\n  method: \"POST\",\n  headers: {\n    \"Authorization\": \"ApiKey YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"prompt\": \"string\",\n    \"images\": [\n      \"string\"\n    ]\n  })\n});\n\nconst data = await response.json();\nconsole.log(data);"
      - lang: Python
        label: Python
        source: "import requests\n\nresponse = requests.post(\n    \"https://api.ludo.ai/api/assets/video/references\",\n    headers={\n        \"Authorization\": \"ApiKey YOUR_API_KEY\",\n        \"Content-Type\": \"application/json\"\n    },\n    json={\n      \"prompt\": \"string\",\n      \"images\": [\n        \"string\"\n      ]\n    }\n)\n\nprint(response.json())"
      x-credit-description: 'This endpoint''s credit cost varies by model and duration (credits/s × seconds, rounded to 0.1; a model''s minimum charge applies when that product is lower). Available models: Griffin (2.5 credits/s, shortest duration 5s, so 12.5 credits minimum; 5s = 12.5, 6s = 15, 7s = 17.5, 8s = 20, 9s = 22.5, 10s = 25, 11s = 27.5, 12s = 30, 13s = 32.5, 14s = 35, 15s = 37.5) · Griffin HD (4 credits/s, shortest duration 5s, so 20 credits minimum; 5s = 20, 6s = 24, 7s = 28, 8s = 32, 9s = 36, 10s = 40, 11s = 44, 12s = 48, 13s = 52, 14s = 56, 15s = 60) · Eagle (1.5 credits/s; 1s = 1.5, 2s = 3, 3s = 4.5, 4s = 6, 5s = 7.5, 6s = 9, 7s = 10.5, 8s = 12, 9s = 13.5, 10s = 15, 11s = 16.5, 12s = 18, 13s = 19.5, 14s = 21, 15s = 22.5) - LEGACY - scheduled for removal, do not use for new work · Eagle with Audio (2 credits/s; 1s = 2, 2s = 4, 3s = 6, 4s = 8, 5s = 10, 6s = 12, 7s = 14, 8s = 16, 9s = 18, 10s = 20, 11s = 22, 12s = 24, 13s = 26, 14s = 28, 15s = 30) - LEGACY - scheduled for removal, do not use for new work'
      x-credit-summary: 'credits/s × seconds, per model: Griffin 2.5/s (shortest duration 5s, so 12.5 credits minimum), Griffin HD 4/s (shortest duration 5s, so 20 credits minimum), Eagle 1.5/s [LEGACY], Eagle with Audio 2/s [LEGACY]; [LEGACY] models are scheduled for removal - do not use them for new work; see this endpoint''s full pricing table in the API docs'
      description: 'Generate a video from 1-5 reference images and a text prompt (references-to-video). Unlike createVideo, which animates a single source image, this composes a new scene that borrows characters, objects, and style from the reference images. Each image can be a URL or base64. Griffin (default, 480p) and Griffin HD (720p) generate a soundtrack; note the per-second rate here is higher than createVideo''s for the same model. The job result is the video URL and its actual duration in seconds. Choose the output shape with `aspect_ratio` ("default" lets the model decide). The chosen `model` and `duration` must be compatible (incompatible combinations return HTTP 400). Credits are held when the job is accepted; the final charge is max(rate × produced seconds, the model''s minimum charge), never more than for the duration you requested, and the difference (or everything, if the job fails or is cancelled) is refunded. Pass an optional `request_id` to tag the result so you can locate it later via listGenerations (type video). Related tools: `createVideo` for image-to-video, `editVideo` to modify a generated video. Requires an API key (user scope). The call returns 202 with a job id - poll getApiJob (pass wait 30 to long-poll) honouring poll_after_ms, until status is succeeded; its result field is exactly the response documented for this operation. Synchronous responses are deprecated but still supported: pass `async: false` to block until the result is ready and receive it as the response body. Synchronous calls run on the same queue: the response carries an X-Ludo-Job-Id header, and a job still running after 15 minutes comes back as 202 with the job instead of an error. Each account may have up to 50 generations queued or running at once via the API; a request beyond that returns 429 (code PENDING_JOBS_LIMIT).


        > **Credits:** This endpoint''s credit cost varies by model and duration (credits/s × seconds, rounded to 0.1; a model''s minimum charge applies when that product is lower). Available models: Griffin (2.5 credits/s, shortest duration 5s, so 12.5 credits minimum; 5s = 12.5, 6s = 15, 7s = 17.5, 8s = 20, 9s = 22.5, 10s = 25, 11s = 27.5, 12s = 30, 13s = 32.5, 14s = 35, 15s = 37.5) · Griffin HD (4 credits/s, shortest duration 5s, so 20 credits minimum; 5s = 20, 6s = 24, 7s = 28, 8s = 32, 9s = 36, 10s = 40, 11s = 44, 12s = 48, 13s = 52, 14s = 56, 15s = 60) · Eagle (1.5 credits/s; 1s = 1.5, 2s = 3, 3s = 4.5, 4s = 6, 5s = 7.5, 6s = 9, 7s = 10.5, 8s = 12, 9s = 13.5, 10s = 15, 11s = 16.5, 12s = 18, 13s = 19.5, 14s = 21, 15s = 22.5) - LEGACY - scheduled for removal, do not use for new work · Eagle with Audio (2 credits/s; 1s = 2, 2s = 4, 3s = 6, 4s = 8, 5s = 10, 6s = 12, 7s = 14, 8s = 16, 9s = 18, 10s = 20, 11s = 22, 12s = 24, 13s = 26, 14s = 28, 15s = 30) - LEGACY - scheduled for removal, do not use for new work.'
      x-mcp-description: 'Generate a video from 1-5 reference images and a text prompt (references-to-video). Unlike createVideo, which animates a single source image, this composes a new scene that borrows characters, objects, and style from the reference images. Each image can be a URL or base64. Griffin (default, 480p) and Griffin HD (720p) generate a soundtrack; note the per-second rate here is higher than createVideo''s for the same model. The job result is the video URL and its actual duration in seconds. Choose the output shape with `aspect_ratio` ("default" lets the model decide). The chosen `model` and `duration` must be compatible (incompatible combinations return HTTP 400). Credits are held when the job is accepted; the final charge is max(rate × produced seconds, the model''s minimum charge), never more than for the duration you requested, and the difference (or everything, if the job fails or is cancelled) is refunded. Pass an optional `request_id` to tag the result so you can locate it later via listGenerations (type video). Related tools: `createVideo` for image-to-video, `editVideo` to modify a generated video. Requires an API key (user scope). The call returns 202 with a job id - poll getApiJob (pass wait 30 to long-poll) honouring poll_after_ms, until status is succeeded; its result field is exactly the response documented for this operation. Synchronous responses are deprecated but still supported: pass `async: false` to block until the result is ready and receive it as the response body. Synchronous calls run on the same queue: the response carries an X-Ludo-Job-Id header, and a job still running after 15 minutes comes back as 202 with the job instead of an error. Each account may have up to 50 generations queued or running at once via the API; a request beyond that returns 429 (code PENDING_JOBS_LIMIT).


        Credits: credits/s × seconds, per model: Griffin 2.5/s (shortest duration 5s, so 12.5 credits minimum), Griffin HD 4/s (shortest duration 5s, so 20 credits minimum), Eagle 1.5/s [LEGACY], Eagle with Audio 2/s [LEGACY]; [LEGACY] models are scheduled for removal - do not use them for new work; see this endpoint''s full pricing table in the API docs.'
    servers:
    - url: /api
  /assets/video/edit:
    post:
      summary: editVideo
      tags:
      - Videos
      operationId: editVideo
      x-credit-action: VIDEO_EDIT
      security:
      - ApiKey: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EditVideoPayloadPublic'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoResult'
        '202':
          description: 'Accepted - the generation was queued; poll GET /assets/jobs/{id}. A synchronous (async: false) call still running after 15 minutes also receives this.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicJob'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-codeSamples:
      - lang: Shell
        label: cURL
        source: "curl -X POST \"https://api.ludo.ai/api/assets/video/edit\" \\\n  -H \"Authorization: ApiKey YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"prompt\":\"string\",\"video\":\"<url>\"}'"
      - lang: JavaScript
        label: JavaScript
        source: "const response = await fetch(\"https://api.ludo.ai/api/assets/video/edit\", {\n  method: \"POST\",\n  headers: {\n    \"Authorization\": \"ApiKey YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"prompt\": \"string\",\n    \"video\": \"<url>\"\n  })\n});\n\nconst data = await response.json();\nconsole.log(data);"
      - lang: Python
        label: Python
        source: "import requests\n\nresponse = requests.post(\n    \"https://api.ludo.ai/api/assets/video/edit\",\n    headers={\n        \"Authorization\": \"ApiKey YOUR_API_KEY\",\n        \"Content-Type\": \"application/json\"\n    },\n    json={\n      \"prompt\": \"string\",\n      \"video\": \"<url>\"\n    }\n)\n\nprint(response.json())"
      x-credit-description: 'This endpoint''s credit cost varies by model and duration (credits/s × seconds, rounded to 0.1; a model''s minimum charge applies when that product is lower). Available models: Griffin HD (2 credits/s, shortest duration 5s, so 10 credits minimum; 5s = 10, 6s = 12, 7s = 14, 8s = 16, 9s = 18, 10s = 20, 11s = 22, 12s = 24, 13s = 26, 14s = 28, 15s = 30) · Eagle (2 credits/s; 1s = 2, 2s = 4, 3s = 6, 4s = 8, 5s = 10, 6s = 12, 7s = 14, 8s = 16, 9s = 18, 10s = 20, 11s = 22, 12s = 24, 13s = 26, 14s = 28, 15s = 30) - LEGACY - scheduled for removal, do not use for new work'
      x-credit-summary: 'credits/s × seconds, per model: Griffin HD 2/s (shortest duration 5s, so 10 credits minimum), Eagle 2/s [LEGACY]; [LEGACY] models are scheduled for removal - do not use them for new work; see this endpoint''s full pricing table in the API docs'
      description: 'Edit a previously generated video with a text prompt and optional reference images (video-to-video); runs on griffin-hd (720p, with soundtrack) and the output keeps the source video''s duration unless you pass one. Pass the video `url` you received from `createVideo`, `createVideoFromReferences`, or an earlier edit - it must be a video you generated within the last 7 days; arbitrary external videos are not accepted. Optionally add up to 5 reference `images` (URL or base64) to guide the edit. The job result is the new video URL and its actual duration in seconds. Credits are held when the job is accepted; the final charge is max(rate × produced seconds, the model''s minimum charge), never more than for the duration you requested, and the difference (or everything, if the job fails or is cancelled) is refunded. Pass an optional `request_id` to tag the result so you can locate it later via listGenerations (type video). Related tools: `createVideo` to generate the source clip, `createVideoFromReferences` for reference-driven generation. Requires an API key (user scope). The call returns 202 with a job id - poll getApiJob (pass wait 30 to long-poll) honouring poll_after_ms, until status is succeeded; its result field is exactly the response documented for this operation. Synchronous responses are deprecated but still supported: pass `async: false` to block until the result is ready and receive it as the response body. Synchronous calls run on the same queue: the response carries an X-Ludo-Job-Id header, and a job still running after 15 minutes comes back as 202 with the job instead of an error. Each account may have up to 50 generations queued or running at once via the API; a request beyond that returns 429 (code PENDING_JOBS_LIMIT).


        > **Credits:** This endpoint''s credit cost varies by model and duration (credits/s × seconds, rounded to 0.1; a model''s minimum charge applies when that product is lower). Available models: Griffin HD (2 credits/s, shortest duration 5s, so 10 credits minimum; 5s = 10, 6s = 12, 7s = 14, 8s = 16, 9s = 18, 10s = 20, 11s = 22, 12s = 24, 13s = 26, 14s = 28, 15s = 30) · Eagle (2 credits/s; 1s = 2, 2s = 4, 3s = 6, 4s = 8, 5s = 10, 6s = 12, 7s = 14, 8s = 16, 9s = 18, 10s = 20, 11s = 22, 12s = 24, 13s = 26, 14s = 28, 15s = 30) - LEGACY - scheduled for removal, do not use for new work.'
      x-mcp-description: 'Edit a previously generated video with a text prompt and optional reference images (video-to-video); runs on griffin-hd (720p, with soundtrack) and the output keeps the source video''s duration unless you pass one. Pass the video `url` you received from `createVideo`, `createVideoFromReferences`, or an earlier edit - it must be a video you generated within the last 7 days; arbitrary external videos are not accepted. Optionally add up to 5 reference `images` (URL or base64) to guide the edit. The job result is the new video URL and its actual duration in seconds. Credits are held when the job is accepted; the final charge is max(rate × produced seconds, the model''s minimum charge), never more than for the duration you requested, and the difference (or everything, if the job fails or is cancelled) is refunded. Pass an optional `request_id` to tag the result so you can locate it later via listGenerations (type video). Related tools: `createVideo` to generate the source clip, `createVideoFromReferences` for reference-driven generation. Requires an API key (user scope). The call returns 202 with a job id - poll getApiJob (pass wait 30 to long-poll) honouring poll_after_ms, until status is succeeded; its result field is exactly the response documented for this operation. Synchronous responses are deprecated but still supported: pass `async: false` to block until the result is ready and receive it as the response body. Synchronous calls run on the same queue: the response carries an X-Ludo-Job-Id header, and a job still running after 15 minutes comes back as 202 with the job instead of an error. Each account may have up to 50 generations queued or running at once via the API; a request beyond that returns 429 (code PENDING_JOBS_LIMIT).


        Credits: credits/s × seconds, per model: Griffin HD 2/s (shortest duration 5s, so 10 credits minimum), Eagle 2/s [LEGACY]; [LEGACY] models are scheduled for removal - do not use them for new work; see this endpoint''s full pricing table in the API docs.'
    servers:
    - url: /api
  /assets/video/upscale:
    post:
      summary: upscaleVideo
      tags:
      - Videos
      operationId: upscaleVideo
      x-credit-action: UPSCALE_VIDEO
      security:
      - ApiKey: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpscaleVideoPayloadPublic'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoResult'
        '202':
          description: 'Accepted - the generation was queued; poll GET /assets/jobs/{id}. A synchronous (async: false) call still running after 15 minutes also receives this.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicJob'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-codeSamples:
      - lang: Shell
        label: cURL
        source: "curl -X POST \"https://api.ludo.ai/api/assets/video/upscale\" \\\n  -H \"Authorization: ApiKey YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"video\":\"<url>\"}'"
      - lang: JavaScript
        label: JavaScript
        source: "const response = await fetch(\"https://api.ludo.ai/api/assets/video/upscale\", {\n  method: \"POST\",\n  headers: {\n    \"Authorization\": \"ApiKey YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    \"video\": \"<url>\"\n  })\n});\n\nconst data = await response.json();\nconsole.log(data);"
      - lang: Python
        label: Python
        source: "import requests\n\nresponse = requests.post(\n    \"https://api.ludo.ai/api/assets/video/upscale\",\n    headers={\n        \"Authorization\": \"ApiKey YOUR_API_KEY\",\n        \"Content-Type\": \"application/json\"\n    },\n    json={\n      \"video\": \"<url>\"\n    }\n)\n\nprint(response.json())"
      x-credit-description: 0.2 credits per second of video
      x-credit-summary: 0.2 credits per second of video
      description: 'Upscale a previously generated video to twice its resolution (2x). Pass the video `url` you received from `createVideo`, `createVideoFromReferences`, or `editVideo` - it must be a video you generated within the last 7 days; arbitrary external videos are not accepted. Both dimensions of the source must be under 960 pixels: griffin (480p) output qualifies; griffin-hd (720p) output does not, landscape or portrait (only a square 720x720 would) - generate on griffin if you intend to upscale. A too-large source fails the job and the held credits are refunded. The job result is the new video URL (2x width and height, same duration) and its duration in seconds. Billed per second of video, independent of model; held when the job is accepted and refunded if it fails or is cancelled. Pass an optional `request_id` to tag the result so you can locate it later via listGenerations (type video). Related tools: `createVideo` for image-to-video, `editVideo` to modify a generated video. Requires an API key (user scope). The call returns 202 with a job id - poll getApiJob (pass wait 30 to long-poll) honouring poll_after_ms, until status is succeeded; its result field is exactly the response documented for this operation. Synchronous responses are deprecated but still supported: pass `async: false` to block until the result is ready and receive it as the response body. Synchronous calls run on the same queue: the response carries an X-Ludo-Job-Id header, and a job still running after 15 minutes comes back as 202 with the job instead of an error. Each account may have up to 50 generations queued or running at once via the API; a request beyond that returns 429 (code PENDING_JOBS_LIMIT).


        > **Credits:** 0.2 credits per second of video.'
      x-mcp-description: 'Upscale a previously generated video to twice its resolution (2x). Pass the video `url` you received from `createVideo`, `createVideoFromReferences`, or `editVideo` - it must be a video you generated within the last 7 days; arbitrary external videos are not accepted. Both dimensions of the source must be under 960 pixels: griffin (480p) output qualifies; griffin-hd (720p) output does not, landscape or portrait (only a square 720x720 would) - generate on griffin if you intend to upscale. A too-large source fails the job and the held credits are refunded. The job result is the new video URL (2x width and height, same duration) and its duration in seconds. Billed per second of video, independent of model; held when the job is accepted and refunded if it fails or is cancelled. Pass an optional `request_id` to tag the result so you can locate it later via listGenerations (type video). Related tools: `createVideo` for image-to-video, `editVideo` to modify a generated video. Requires an API key (user scope). The call returns 202 with a job id - poll getApiJob (pass wait 30 to long-poll) honouring poll_after_ms, until status is succeeded; its result field is exactly the response documented for this operation. Synchronous responses are deprecated but still supported: pass `async: false` to block until the result is ready and receive it as the response body. Synchronous calls run on the same queue: the response carries an X-Ludo-Job-Id header, and a job still running after 15 minutes comes back as 202 with the job instead of an error. Each account may have up to 50 generations queued or running at once via the API; a request beyond that returns 429 (code PENDING_JOBS_LIMIT).


        Credits: 0.2 credits per second of video.'
    servers:
    - url: /api
  /assets/videos/results:
    get:
      description: '**Deprecated:** prefer `GET /assets/generations` (all types, paginated, same source filter). This endpoint continues to work; no removal is scheduled.

        List videos you previously generated through the API, most recent first. This is a free read-only history lookup (no credits, no generation); it does not create anything. Pass an optional request_id query parameter to return only the results tagged with that id when you originally called createVideo. Requires an API key (user scope).'
      tags:
      - Videos
      operationId: getVideoResults
      deprecated: true
      x-mcp-exclude: true
      security:
      - ApiKey: []
      parameters:
      - name: request_id
        in: query
        description: Filter results by request_id
        required: false
        schema:
          type: string
      - name: source
        in: query
        description: 'Which surface the results were generated from: api (default, your API/MCP generations from the last 7 days), web (your Ludo web studio generations, no time limit), or all'
        required: false
        schema:
          type: string
          enum:
          - api
          - web
          - all
          default: api
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/VideoResult'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-codeSamples:
      - lang: Shell
        label: cURL
        source: "curl -X GET \"https://api.ludo.ai/api/assets/videos/results\" \\\n  -H \"Authorization: ApiKey YOUR_API_KEY\""
      - lang: JavaScript
        label: JavaScript
        source: "const response = await fetch(\"https://api.ludo.ai/api/assets/videos/results\", {\n  headers: {\n    \"Authorization\": \"ApiKey YOUR_API_KEY\"\n  }\n});\n\nconst data = await response.json();\nconsole.log(data);"
      - lang: Python
        label: Python
        source: "import requests\n\nresponse = requests.get(\n    \"https://api.ludo.ai/api/assets/videos/results\",\n    headers={\"Authorization\": \"ApiKey YOUR_API_KEY\"}\n)\n\nprint(response.json())"
      summary: Get video results
      x-summary-source: derived
    servers:
    - url: /api
components:
  schemas:
    EditVideoPayloadPublic:
      type: object
      description: Payload for editing a previously generated video with a text prompt and optional reference images.
      required:
      - prompt
      - video
      properties:
        video:
          type: string
          description: URL of a video you generated in the last 7 days (returned by createVideo, createVideoFromReferences, or a previous edit). External URLs are not accepted.
        prompt:
          type: string
          description: Edit instruction describing the desired change.
        images:
          type: array
          maxItems: 5
          items:
            type: string
          description: Optional reference images (up to 5), each a URL or base64, to guide the edit.
        duration:
          type: number
          format: float
          description: 'Duration in seconds. Available values depend on the model:

            - griffin-hd: 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15

            - eagle: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15'
        model:
          type: string
          description: 'Model to use. Available models:

            - "griffin-hd" (Griffin HD): 2 credits/s, shortest duration 5s, so 10 credits minimum · Same as Griffin, but in 720p

            - "eagle" (Eagle): 2 credits/s · LEGACY - scheduled for removal, do not use for new work

            Models marked LEGACY still work for existing integrations but will be removed; pick a current model for anything new.'
          enum:
          - griffin-hd
          - eagle
          default: griffin-hd
          example: griffin-hd
        request_id:
          type: string
          description: Optional client-provided identifier, unique per request. Re-sending the same request_id returns the existing job instead of generating again. Also usable as the request_id filter of listGenerations.
        async:
          type: boolean
          default: true
          description: 'Defaults to true: the call returns 202 immediately with a job id to poll with getApiJob. Set false for a synchronous response (deprecated but supported): the call then blocks until the result is ready.'
          example: true
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
        metadata:
          type: string
        error_payload:
          type: string
        intent:
          type: object
          description: Stripe intent details sent with 3D Secure (406) errors
          properties:
            id:
              type: string
            type:
              type: string
              enum:
              - payment
              - setup
              example: payment
            client_secret:
              type: string
    GenerateVideoPayloadPublic:
      type: object
      description: Payload for generating a video from a source image and motion prompt
      required:
      - image
      - prompt
      properties:
        image:
          type: string
          description: URL or base64-encoded source image (the starting frame for the video)
          example: <url> OR data:image/png;base64,...
        prompt:
          type: string
          description: Text description of the motion or action for the video (e.g., "walking forward", "waving hand", "camera zoom in")
        augment_prompt:
          type: boolean
          default: true
          description: Rewrites your prompt behind the scenes into the form the model works best with. Leave it on (the default). Turning it off does not give you more control - it usually gives worse results. Do not disable it unless you really know what you are doing and have tested your prompts extensively.
          example: true
        final_image:
          type: string
          description: URL or base64-encoded end frame image. When provided, the video will interpolate between the initial and final frames.
          example: <url> OR data:image/png;base64,...
        duration:
          type: number
          format: float
          default: 5
          description: 'Duration in seconds. Available values depend on the model:

            - griffin: 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15

            - griffin-hd: 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15

            - blitz: 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12

            - eagle: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15

            - eagle-audio: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15'
          example: 5
        model:
          type: string
          description: 'Model to use. Available models:

            - "griffin" (Griffin): 1.5 credits/s, shortest duration 5s, so 7.5 credits minimum · Fast cinematic videos in any style, with audio, 480p

            - "griffin-hd" (Griffin HD): 2 credits/s, shortest duration 5s, so 10 credits minimum · Same as Griffin, but in 720p

            - "blitz" (Blitz): 1 credits/s, shortest duration 2s, so 2 credits minimum · LEGACY - scheduled for removal, do not use for new work

            - "eagle" (Eagle): 1.3 credits/s · LEGACY - scheduled for removal, do not use for new work

            - "eagle-audio" (Eagle with Audio): 1.8 credits/s · LEGACY - scheduled for removal, do not use for new work

            Legacy aliases: "standard" → blitz.

            Models marked LEGACY still work for existing integrations but will be removed; pick a current model for anything new.'
          enum:
          - griffin
          - griffin-hd
          - blitz
          - standard
          - eagle
          - eagle-audio
          default: griffin
          example: griffin
        request_id:
          type: string
          description: Optional client-provided identifier, unique per request. Re-sending the same request_id returns the existing job instead of generating again. Also usable as the request_id filter of listGenerations.
        async:
          type: boolean
          default: true
          description: 'Defaults to true: the call returns 202 immediately with a job id to poll with getApiJob. Set false for a synchronous response (deprecated but supported): the call then blocks until the result is ready.'
          example: true
    PublicJobError:
      type: object
      properties:
        status:
          type: integer
          format: int32
        message:
          type: string
    VideoResult:
      type: object
      properties:
        url:
          type: string
          description: URL to the generated video file
          example: <url>
        duration:
          type: number
          format: float
          description: Duration of the video in seconds
        has_audio:
          type: boolean
        request_id:
          type: string
        created_at:
          type: integer
    UpscaleVideoPayloadPublic:
      type: object
      description: Payload for upscaling a previously generated video to twice its resolution.
      required:
      - video
      properties:
        video:
          type: string
          description: URL of a video you generated in the last 7 days (returned by createVideo, createVideoFromReferences, or editVideo). External URLs are not accepted. Both dimensions must be under 960 pixels (griffin 480p output qualifies; griffin-hd 720p output does not, except square).
        request_id:
          type: string
          description: Optional client-provided identifier, unique per request. Re-sending the same request_id returns the existing job instead of generating again. Also usable as the request_id filter of listGenerations.
        async:
          type: boolean
          default: true
          description: 'Defaults to true: the call returns 202 immediately with a job id to poll with getApiJob. Set false for a synchronous response (deprecated but supported): the call then blocks until the result is ready.'
          example: true
    ReferencesToVideoPayloadPublic:
      type: object
      description: Payload for generating a video from 1-5 reference images and a text prompt.
      required:
      - prompt
      - images
      properties:
        prompt:
          type: string
          description: Text description of the video to generate.
        images:
          type: array
          minItems: 1
          maxItems: 5
          items:
            type: string
          description: Reference images (1 to 5), each a URL or base64. The generated video borrows characters, objects, and style from them.
        duration:
          type: number
          format: float
          default: 5
          description: 'Duration in seconds. Available values depend on the model:

            - griffin: 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15

            - griffin-hd: 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15

            - eagle: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15

            - eagle-audio: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15'
          example: 5
        model:
          type: string
          description: 'Model to use. Available models:

            - "griffin" (Griffin): 2.5 credits/s, shortest duration 5s, so 12.5 credits minimum · Fast cinematic videos in any style, with audio, 480p

            - "griffin-hd" (Griffin HD): 4 credits/s, shortest duration 5s, so 20 credits minimum · Same as Griffin, but in 720p

            - "eagle" (Eagle): 1.5 credits/s · LEGACY - scheduled for removal, do not use for new work

            - "eagle-audio" (Eagle with Audio): 2 credits/s · LEGACY - scheduled for removal, do not use for new work

            Models marked LEGACY still work for existing integrations but will be removed; pick a current model for anything new.'
          enum:
          - griffin
          - griffin-hd
          - eagle
          - eagle-audio
          default: griffin
          example: griffin
        aspect_ratio:
          type: string
          description: Output aspect ratio. "default" lets the model choose.
          enum:
          - default
          - ar_1_1
          - ar_16_9
          - ar_9_16
          - ar_4_3
          - ar_3_4
          - ar_21_9
          default: default
          example: default
        request_id:
          type: string
          description: Optional client-provided identifier, unique per request. Re-sending the same request_id returns the existing job instead of generating again. Also usable as the request_id filter of listGenerations.
        async:
          type: boolean
          default: true
          description: 'Defaults to true: the call returns 202 immediately with a job id to poll with getApiJob. Set false for a synchronous response (deprecated but supported): the call then blocks until the result is ready.'
          example: true
    PublicJob:
      type: object
      required:
      - id
      - task_type
      - status
      - created_at
      properties:
        id:
          type: string
        task_type:
          type: string
          description: 'The public operationId that created this job (e.g. createImage). Determines the shape of `result`: it is exactly the 200 response body documented for that operation.'
        status:
          type: string
          enum:
          - queued
          - running
          - succeeded
          - failed
          - canceled
          example: queued
        request_id:
          type: string
        created_at:
          type: integer
          format: int64
          description: Unix ms
        finished_at:
          type: integer
          format: int64
        credits_charged:
          type: number
          format: float
          description: Credits this job cost you. Charged at enqueue; reported as 0 once a job fails or is canceled, since the charge is refunded.
        result:
          type: object
          description: Present only when status is succeeded. Same shape as the synchronous response of the operation named by task_type.
        error:
          $ref: '#/components/schemas/PublicJobError'
        poll_after_ms:
          type: integer
          format: int32
          description: 'Present while the job is queued or running: wait at least this many milliseconds before polling again. Prefer GET /assets/jobs/{id}?wait=30 (long-poll) over tight loops.'
  securitySchemes:
    ApiKey:
      type: apiKey
      name: Authorization
      in: header
      description: 'For accessing the API a valid API Key token must be passed in all the queries in

        the ''Authorization'' header.

        The following syntax must be used in the ''Authorization'' header: ApiKey xxxxxx.yyyyyyy.zzzzzz

        '
x-refined-from:
- ludo-ai-rest-api-openapi.yml
- ludo-ai-openapi.json