{
  "openapi": "3.1.0",
  "info": {
    "title": "Bildy API",
    "version": "1.8.0",
    "description": "Public API for Bildy image and video generation, video editing, credits and Notes Memory. Generating is a job: start it, poll its job endpoint until the status is completed, then download within the hour.\n\nLimits: images 20 requests a minute; videos 30 an hour; video edits 120 an hour; everything else 60 a minute per key. A request body tops out at 6 MB, and inline base64 images share a 5.2 MB budget across at most 4 images. An image named by URL (imageUrls, imageUrl, lastFrameUrl, referenceImageUrls) is fetched by us and does not count against the body. A file on your own machine gets a URL through POST /uploads.\n\nRetries: every submit accepts an Idempotency-Key header (or idempotencyKey in the body). If the answer to a submit is lost, resend with the same key and you get the same job back with no second charge and data.replayed set to true; a retry while the first is still running answers 409 request_in_flight with Retry-After. Job reads are GETs and safe to retry as they are.",
    "contact": {
      "email": "support@bildy.ai"
    }
  },
  "servers": [
    {
      "url": "https://bildy.ai/api/v1",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Notes Memory",
      "description": "API-key-scoped Notes memory folders for external apps and agents."
    },
    {
      "name": "Images",
      "description": "Generating and editing images."
    },
    {
      "name": "Videos",
      "description": "Generating short video clips."
    },
    {
      "name": "Credits",
      "description": "What the account has left to spend."
    },
    {
      "name": "Files",
      "description": "Getting a file from your own machine into Bildy."
    }
  ],
  "x-agent-guidance": {
    "entrypoints": [
      "https://bildy.ai/api-agent-manifest.json",
      "https://bildy.ai/api-docs"
    ],
    "rules": [
      "Use only /api/v1 endpoints.",
      "Treat ids as opaque strings.",
      "Use PATCH for partial updates instead of recreating resources."
    ],
    "workflows": {
      "quickPost": [],
      "agentAuthoredPost": [],
      "placedPost": []
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key"
      }
    },
    "parameters": {
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string",
          "maxLength": 255
        },
        "description": "Any string unique to this one request. Resend with the same key if the answer is lost and you get the original job back, with no second charge. idempotencyKey in the body does the same. A replayed answer carries data.replayed: true."
      }
    },
    "schemas": {
      "ErrorEnvelope": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string"
              },
              "code": {
                "type": "string"
              }
            },
            "required": [
              "message"
            ]
          }
        },
        "required": [
          "error"
        ]
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Bad request",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Invalid or missing API key",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "InsufficientCredits": {
        "description": "Not enough credits",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "UnsupportedMediaType": {
        "description": "Content-Type must be application/json",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "ServerError": {
        "description": "Server error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "RequestInFlight": {
        "description": "A request with this Idempotency-Key is still running (code request_in_flight). Retry after the Retry-After seconds to get its result.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      },
      "PayloadTooLarge": {
        "description": "The body, or the inline images in it, are over what a request can carry (code image_too_large or too_large). Send fewer or smaller images, or name them by URL.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      }
    }
  },
  "paths": {
    "/notes/upsert": {
      "post": {
        "tags": [
          "Notes Memory"
        ],
        "operationId": "upsertNoteMemory",
        "summary": "Create or update a Notes memory note",
        "description": "Creates or replaces a note in a named Notes folder. The Bearer API key resolves the user account; do not pass userId.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "folder",
                  "title",
                  "content"
                ],
                "properties": {
                  "folder": {
                    "type": "string",
                    "example": "support-memory"
                  },
                  "title": {
                    "type": "string",
                    "example": "Important Facts"
                  },
                  "content": {
                    "type": "string",
                    "example": "The customer prefers invoices by email."
                  },
                  "id": {
                    "type": "string",
                    "description": "Optional explicit note id."
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "kind": {
                    "type": "string",
                    "example": "summary"
                  },
                  "metadata": {
                    "type": "object",
                    "additionalProperties": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Note created or updated"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/notes/append": {
      "post": {
        "tags": [
          "Notes Memory"
        ],
        "operationId": "appendNoteMemory",
        "summary": "Append to a Notes memory note",
        "description": "Appends content to a note in a named Notes folder. Useful for conversation logs and action logs.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "folder",
                  "title",
                  "content"
                ],
                "properties": {
                  "folder": {
                    "type": "string",
                    "example": "support-memory"
                  },
                  "title": {
                    "type": "string",
                    "example": "Conversation Log"
                  },
                  "content": {
                    "type": "string",
                    "example": "2026-05-19: Customer asked about invoice timing."
                  },
                  "id": {
                    "type": "string"
                  },
                  "separator": {
                    "type": "string",
                    "default": "\n\n"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Note appended"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/notes/list": {
      "get": {
        "tags": [
          "Notes Memory"
        ],
        "operationId": "listNoteMemory",
        "summary": "List Notes memory notes",
        "parameters": [
          {
            "name": "folder",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 100
            }
          },
          {
            "name": "includeContent",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Notes listed"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/notes/get": {
      "get": {
        "tags": [
          "Notes Memory"
        ],
        "operationId": "getNoteMemory",
        "summary": "Get one Notes memory note",
        "parameters": [
          {
            "name": "folder",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "title",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Note loaded"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/notes/search": {
      "post": {
        "tags": [
          "Notes Memory"
        ],
        "operationId": "searchNoteMemory",
        "summary": "Search Notes memory",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "folder",
                  "query"
                ],
                "properties": {
                  "folder": {
                    "type": "string",
                    "example": "support-memory"
                  },
                  "query": {
                    "type": "string",
                    "example": "invoice timing"
                  },
                  "limit": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 50,
                    "default": 10
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Search results"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/notes/recall": {
      "post": {
        "tags": [
          "Notes Memory"
        ],
        "operationId": "recallNoteMemory",
        "summary": "Recall Notes memory context",
        "description": "Returns compact context and source excerpts from a named Notes memory folder.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "folder",
                  "query"
                ],
                "properties": {
                  "folder": {
                    "type": "string",
                    "example": "support-memory"
                  },
                  "query": {
                    "type": "string",
                    "example": "What should I know before replying to ACME?"
                  },
                  "limit": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 20,
                    "default": 5
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Memory context"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/notes/delete": {
      "delete": {
        "tags": [
          "Notes Memory"
        ],
        "operationId": "deleteNoteMemory",
        "summary": "Delete a Notes memory note",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "folder"
                ],
                "properties": {
                  "folder": {
                    "type": "string",
                    "example": "support-memory"
                  },
                  "id": {
                    "type": "string"
                  },
                  "title": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Note deleted"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/images/generate": {
      "post": {
        "tags": [
          "Images"
        ],
        "summary": "Make an image from a prompt",
        "description": "Starts a generation and answers with a job id. Poll /images/jobs/{jobId} until the status is completed or failed. Credits are reserved when the job starts; a generation that produces fewer images than you paid for refunds the difference when it finishes.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "prompt"
                ],
                "properties": {
                  "prompt": {
                    "type": "string",
                    "description": "What the image should show."
                  },
                  "model": {
                    "type": "string",
                    "description": "Optional model id from /images/models. Left out, Muse Image (openrouter-muse-image) is used. Each id makes one size; Nano Banana 2 at 2K (2048px on the long side; GET /images/models has its price) is its own id, gemini-3.1-flash-image-2k."
                  },
                  "ratio": {
                    "type": "string",
                    "description": "Optional aspect ratio, for example 1:1 or 16:9."
                  },
                  "variations": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 4,
                    "description": "How many images to make. Each costs the model price."
                  },
                  "idempotencyKey": {
                    "type": "string",
                    "maxLength": 255,
                    "description": "Same as the Idempotency-Key header, for clients that cannot set headers."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "The job started",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "jobId": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        },
                        "pollUrl": {
                          "type": "string"
                        },
                        "replayed": {
                          "type": "boolean",
                          "description": "Present and true only when this answer was replayed for a repeated Idempotency-Key. The jobId is the original job's and nothing was charged again."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Not enough credits"
          },
          "429": {
            "description": "Rate limited"
          },
          "409": {
            "$ref": "#/components/responses/RequestInFlight"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ]
      }
    },
    "/images/edit": {
      "post": {
        "tags": [
          "Images"
        ],
        "summary": "Change images you send",
        "description": "Same as /images/generate, with one to four images to work from. Send at least one image, as images (base64) or imageUrls (links we fetch).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "prompt"
                ],
                "properties": {
                  "prompt": {
                    "type": "string",
                    "description": "What the image should show."
                  },
                  "model": {
                    "type": "string",
                    "description": "Optional model id from /images/models. Left out, Muse Image (openrouter-muse-image) is used. Each id makes one size; Nano Banana 2 at 2K (2048px on the long side; GET /images/models has its price) is its own id, gemini-3.1-flash-image-2k."
                  },
                  "ratio": {
                    "type": "string",
                    "description": "Optional aspect ratio, for example 1:1 or 16:9."
                  },
                  "variations": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 4,
                    "description": "How many images to make. Each costs the model price."
                  },
                  "images": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "maxItems": 4,
                    "description": "One to four base64 images. A data: prefix is fine. Inline images share a 5.2 MB budget per request; for anything bigger use imageUrls."
                  },
                  "idempotencyKey": {
                    "type": "string",
                    "maxLength": 255,
                    "description": "Same as the Idempotency-Key header, for clients that cannot set headers."
                  },
                  "imageUrls": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uri"
                    },
                    "maxItems": 4,
                    "description": "Public https links to pictures instead of their bytes; we fetch them. They skip the 6 MB body limit. At most 4 images in total across images and imageUrls. Private and internal addresses are refused."
                  }
                },
                "anyOf": [
                  {
                    "required": [
                      "images"
                    ]
                  },
                  {
                    "required": [
                      "imageUrls"
                    ]
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "The job started",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "jobId": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        },
                        "pollUrl": {
                          "type": "string"
                        },
                        "replayed": {
                          "type": "boolean",
                          "description": "Present and true only when this answer was replayed for a repeated Idempotency-Key. The jobId is the original job's and nothing was charged again."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Not enough credits"
          },
          "429": {
            "description": "Rate limited"
          },
          "409": {
            "$ref": "#/components/responses/RequestInFlight"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ]
      }
    },
    "/images/jobs/{jobId}": {
      "get": {
        "tags": [
          "Images"
        ],
        "summary": "Read an image job",
        "description": "While the job runs the status is pending or processing. Once completed, each image has a download link good for an hour; poll again for a fresh one. Add includeBase64=true to get the bytes inline as well.",
        "parameters": [
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "includeBase64",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The job as it stands",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "jobId": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "pending",
                            "processing",
                            "completed",
                            "failed"
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No such job for this key"
          }
        }
      }
    },
    "/images/models": {
      "get": {
        "tags": [
          "Images"
        ],
        "summary": "List image models",
        "description": "Every model you can name, with what one image costs on each. No key needed: this list is public and rate limited by address.",
        "responses": {
          "200": {
            "description": "The models you can name"
          }
        },
        "security": []
      }
    },
    "/videos/generate": {
      "post": {
        "tags": [
          "Videos"
        ],
        "summary": "Make a clip",
        "description": "Starts a clip and answers with a job id. The first frame comes as image (base64) or imageUrl (a link we fetch), and on models with a last frame slot the last frame comes as lastFrame or lastFrameUrl. Credits are charged when the job starts and refunded if it cannot be handed to a worker. A clip takes minutes, so poll /videos/jobs/{jobId}.\n\nModels with maxReferenceImages above 0 in /videos/models also take reference pictures, and a storyboard from /videos/storyboards. We send the storyboard first, then referenceImages, then referenceImageUrls. Some models take a first frame or references, never both (framesOrReferences in /videos/models). References do not change the price, which stays the model's price for the clip length, but Veo makes every clip from references 8 seconds long, so that is the length we make and bill. We answer 400 to any problem with the pictures before anything is charged.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "prompt"
                ],
                "properties": {
                  "prompt": {
                    "type": "string",
                    "description": "What should happen in the clip, including any camera movement."
                  },
                  "imageUrl": {
                    "type": "string",
                    "format": "uri",
                    "description": "Optional first frame as a public https link, which we fetch (PNG, JPEG or WebP, up to 8 MB): a link an image job or a frame edit gave you, a POST /uploads link, or any public picture. Send image or imageUrl, not both. Some models need a first frame; /videos/models says which."
                  },
                  "image": {
                    "type": "string",
                    "description": "Optional base64 first frame, a data: prefix is fine. It shares the 5.2 MB inline budget; use imageUrl for anything bigger."
                  },
                  "lastFrameUrl": {
                    "type": "string",
                    "format": "uri",
                    "description": "Optional last frame as a public https link, for models whose image slots in /videos/models include a last frame. Some of them only take it together with a first frame, and models that take a first frame or references never take a last frame beside references."
                  },
                  "lastFrame": {
                    "type": "string",
                    "description": "The last frame as base64 instead of a link. Send lastFrame or lastFrameUrl, not both."
                  },
                  "model": {
                    "type": "string",
                    "description": "Optional model id from /videos/models."
                  },
                  "ratio": {
                    "type": "string",
                    "description": "Optional aspect ratio, for example 16:9 or 9:16."
                  },
                  "seconds": {
                    "type": "number",
                    "description": "Clip length. /videos/models lists what each model allows and what it costs. With reference pictures, Veo only makes 8 second clips: leave this out or send 8."
                  },
                  "idempotencyKey": {
                    "type": "string",
                    "maxLength": 255,
                    "description": "Same as the Idempotency-Key header, for clients that cannot set headers."
                  },
                  "referenceImageUrls": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uri"
                    },
                    "description": "Public https links to reference pictures, such as a person or a product the clip should keep. We fetch them (PNG, JPEG or WebP, up to 8 MB each). Only models with maxReferenceImages above 0 take them."
                  },
                  "referenceImages": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "The same as base64. They share the 5.2 MB inline budget with image and storyboard, so use referenceImageUrls for anything big."
                  },
                  "storyboardUrl": {
                    "type": "string",
                    "format": "uri",
                    "description": "The url of a storyboard from /videos/storyboards. We send it as the first reference picture, so on models that cite references by tag it is image 1, and we put an instruction to follow its panels ahead of your prompt. It counts toward the model's reference limit."
                  },
                  "storyboard": {
                    "type": "string",
                    "description": "A storyboard as base64 instead of a link. Send storyboard or storyboardUrl, not both."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "The job started",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "jobId": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        },
                        "pollUrl": {
                          "type": "string"
                        },
                        "replayed": {
                          "type": "boolean",
                          "description": "Present and true only when this answer was replayed for a repeated Idempotency-Key. The jobId is the original job's and nothing was charged again."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Not enough credits"
          },
          "429": {
            "description": "Rate limited"
          },
          "409": {
            "$ref": "#/components/responses/RequestInFlight"
          },
          "400": {
            "description": "The request cannot work, and nothing was charged. The code says why: bad_request (a missing or malformed field), unknown_model, image_required (the model needs a first frame), references_not_supported (the model takes no reference pictures), too_many_references (more than the model takes, the storyboard counting as one), frames_or_references (the model takes a first frame or references, never both), first_frame_not_supported, last_frame_not_supported (the model takes no last frame), last_frame_needs_first (the model takes a last frame only beside a first frame), seconds_fixed_with_references (Veo with references only makes 8 second clips), images_not_supported (any other mix of pictures the model cannot take), bad_remote_url (a link we could not fetch).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ]
      }
    },
    "/videos/storyboards": {
      "post": {
        "tags": [
          "Videos"
        ],
        "summary": "Draw storyboards for a clip",
        "description": "The first step of a clip made from a storyboard. Each storyboard is a grid of pencil sketches, one panel per shot, drawn from your prompt on gemini-3.1-flash-image (Nano Banana 2) at 16:9. It is an image job: poll /images/jobs/{jobId} until it is completed, show the storyboards to the person or pick one, then pass the chosen one's url to /videos/generate as storyboardUrl, with the same prompt, within the hour the link lasts. Each storyboard costs that model's price per image in /images/models.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "prompt"
                ],
                "properties": {
                  "prompt": {
                    "type": "string",
                    "description": "What happens in the clip. Send the same prompt to /videos/generate afterwards."
                  },
                  "count": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 4,
                    "default": 4,
                    "description": "How many storyboards to draw, so there is a choice. Each costs the price of one image."
                  },
                  "seconds": {
                    "type": "number",
                    "description": "How long the clip will be. It decides how many panels each storyboard has: 3 up to 5 seconds, 4 up to 8, 6 above that."
                  },
                  "ratio": {
                    "type": "string",
                    "enum": [
                      "16:9",
                      "9:16",
                      "1:1",
                      "4:3",
                      "3:4",
                      "21:9",
                      "9:21"
                    ],
                    "description": "The clip's shape. Each panel is drawn in it; the storyboard itself is always 16:9."
                  },
                  "images": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "maxItems": 4,
                    "description": "Optional base64 pictures of the people, products or places in the clip, so the storyboard shows them. A data: prefix is fine. Inline images share a 5.2 MB budget per request."
                  },
                  "imageUrls": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uri"
                    },
                    "maxItems": 4,
                    "description": "The same pictures as public https links, which we fetch. At most 4 images in total across images and imageUrls."
                  },
                  "idempotencyKey": {
                    "type": "string",
                    "maxLength": 255,
                    "description": "Same as the Idempotency-Key header, for clients that cannot set headers."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "The job started",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "jobId": {
                          "type": "string",
                          "description": "Poll /images/jobs/{jobId} with this."
                        },
                        "status": {
                          "type": "string"
                        },
                        "creditsReserved": {
                          "type": "integer",
                          "description": "Credits held for every storyboard asked for. Any that are not drawn are given back."
                        },
                        "creditsPerImage": {
                          "type": "integer",
                          "description": "What one storyboard costs."
                        },
                        "requestedImages": {
                          "type": "integer",
                          "description": "How many storyboards were asked for."
                        },
                        "pollUrl": {
                          "type": "string"
                        },
                        "replayed": {
                          "type": "boolean",
                          "description": "Present and true only when this answer was replayed for a repeated Idempotency-Key. The jobId is the original job's and nothing was charged again."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request cannot work (code bad_request): no prompt, a count outside 1 to 4, seconds or ratio no video model makes, a model named (storyboards always use the same one), or a picture that is not valid. We answer bad_remote_url for a link we cannot fetch.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "402": {
            "description": "Not enough credits"
          },
          "409": {
            "$ref": "#/components/responses/RequestInFlight"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "description": "Rate limited. Storyboards count against the image limit."
          }
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ]
      }
    },
    "/videos/jobs/{jobId}": {
      "get": {
        "tags": [
          "Videos"
        ],
        "summary": "Read a video job",
        "description": "Once completed the clip has a download link good for an hour; poll again for a fresh one.",
        "parameters": [
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The job as it stands",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "jobId": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "pending",
                            "processing",
                            "completed",
                            "failed"
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No such job for this key"
          }
        }
      }
    },
    "/videos/models": {
      "get": {
        "tags": [
          "Videos"
        ],
        "summary": "List video models",
        "description": "Every video model, the clip lengths it allows and what each length costs. maxReferenceImages is how many reference pictures, a storyboard included, /videos/generate may send it, and framesOrReferences is true when it takes a first frame or references but never both. No key needed: this list is public and rate limited by address.",
        "responses": {
          "200": {
            "description": "The models you can name"
          }
        },
        "security": []
      }
    },
    "/videos/edit": {
      "post": {
        "tags": [
          "Videos"
        ],
        "summary": "Edit a clip: take a frame, join clips and pictures, trim, lay sound over, cut a timeline of shots, or join rendered parts under a song",
        "description": "No model runs for these; they are ffmpeg on our own machine and cost a flat few credits per call (frame 5, trim 10, audio 10, compose 25, timeline 50, join 10). Answers with a job id; poll /videos/edits/{jobId}. Each item is a link a Bildy job gave you or any public https link, or bytes inline (base64) up to 50 MB.\n\ntimeline cuts up to 60 seconds of video (up to 150 cuts, 1080p) the way an editor does: each item is a cut with its seconds on screen, where to start in its clip, a speed, a transition into it and an optional grade, and the whole render gets a grade, grain, a vignette, fades and lyrics burned in from an ASS file (subtitles or subtitlesUrl; every style is drawn in Archivo Black). A cut names its clip by videoJobId, its picture by imageJobId and imageIndex, a finished edit by editJobId, or anything by url, and job ids need no fresh link. For a whole song, render it in parts of up to 60 seconds with subtitlesOffsetSeconds set to where each part starts, then join. join puts parts from timeline end to end without encoding them again (they must share a size and fps) and lays audioUrl under them from audioStartSeconds.",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "operation",
                  "items"
                ],
                "properties": {
                  "operation": {
                    "type": "string",
                    "enum": [
                      "frame",
                      "compose",
                      "trim",
                      "audio",
                      "timeline",
                      "join"
                    ],
                    "description": "frame: one frame out of a clip. compose: pictures and clips end to end. trim: one stretch of a clip. audio: a sound file laid over a clip. timeline: cut a video from a list of shots. join: parts from timeline end to end under a song."
                  },
                  "items": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 150,
                    "description": "frame and trim take one video item; audio takes the video then the audio file; compose takes 1 to 20 images and videos in order; timeline takes 1 to 150 cuts in order; join takes 1 to 30 parts in order.",
                    "items": {
                      "type": "object",
                      "properties": {
                        "kind": {
                          "type": "string",
                          "enum": [
                            "image",
                            "video",
                            "audio"
                          ],
                          "description": "timeline: image or video. join: leave out."
                        },
                        "url": {
                          "type": "string",
                          "format": "uri",
                          "description": "A public https link, or one a Bildy job gave you."
                        },
                        "base64": {
                          "type": "string",
                          "description": "The file inline instead of a link, up to 50 MB."
                        },
                        "seconds": {
                          "type": "number",
                          "description": "compose, images only: how long it stays on screen, 3 if left out. timeline, every cut: how long the cut stays on screen (0.1 to 60), required."
                        },
                        "startSeconds": {
                          "type": "number",
                          "description": "compose and timeline, videos only: where to start using it."
                        },
                        "endSeconds": {
                          "type": "number",
                          "description": "compose, videos only: where to stop using it."
                        },
                        "videoJobId": {
                          "type": "string",
                          "description": "timeline: a finished clip from /videos/generate, instead of url."
                        },
                        "imageJobId": {
                          "type": "string",
                          "description": "timeline: a finished image job, polled to completed, instead of url."
                        },
                        "imageIndex": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 3,
                          "description": "timeline: which picture of that image job. 0 if left out."
                        },
                        "editJobId": {
                          "type": "string",
                          "description": "timeline or join: a finished edit (a timeline part, a frame), instead of url."
                        },
                        "speed": {
                          "type": "number",
                          "minimum": 0.25,
                          "maximum": 4,
                          "description": "timeline, videos only: 0.5 plays at half speed, 2 at double. 1 if left out."
                        },
                        "transition": {
                          "type": "string",
                          "enum": [
                            "cut",
                            "flash",
                            "dip",
                            "dissolve",
                            "fadeblack",
                            "fadewhite",
                            "whip",
                            "slide",
                            "wipe",
                            "zoom",
                            "glitch",
                            "circle",
                            "blur",
                            "radial"
                          ],
                          "description": "timeline: how this cut comes in. A crossfade lets the cut before run on under this one, so this one still starts on its beat. cut if left out."
                        },
                        "transitionSeconds": {
                          "type": "number",
                          "minimum": 0.05,
                          "maximum": 2,
                          "description": "timeline: the transition's length, if not its usual one."
                        },
                        "zoom": {
                          "type": "string",
                          "enum": [
                            "in",
                            "out",
                            "none"
                          ],
                          "description": "timeline, images only: a slow push in (the default), a pull out, or a still."
                        },
                        "grade": {
                          "type": "string",
                          "enum": [
                            "none",
                            "film",
                            "warm",
                            "cool",
                            "bleach",
                            "vivid",
                            "noir",
                            "night"
                          ],
                          "description": "timeline: a grade for this cut only."
                        }
                      },
                      "description": "One file. Every operation but join needs kind."
                    }
                  },
                  "frame": {
                    "description": "frame only: \"first\", \"last\" (the default), or a number of seconds from the start.",
                    "oneOf": [
                      {
                        "type": "string",
                        "enum": [
                          "first",
                          "last"
                        ]
                      },
                      {
                        "type": "number",
                        "minimum": 0
                      }
                    ]
                  },
                  "startSeconds": {
                    "type": "number",
                    "description": "trim only: where the kept stretch starts. 0 if left out."
                  },
                  "endSeconds": {
                    "type": "number",
                    "description": "trim only: where it ends. The end of the clip if left out."
                  },
                  "width": {
                    "type": "integer",
                    "minimum": 16,
                    "maximum": 4096,
                    "description": "compose only: force a frame width. Give both or neither; the first clip decides otherwise. timeline: 1920 if left out, up to 1920x1080 or 1080x1920."
                  },
                  "height": {
                    "type": "integer",
                    "minimum": 16,
                    "maximum": 4096
                  },
                  "fps": {
                    "type": "integer",
                    "enum": [
                      24,
                      25,
                      30
                    ],
                    "description": "timeline: 24 if left out."
                  },
                  "grade": {
                    "type": "string",
                    "enum": [
                      "none",
                      "film",
                      "warm",
                      "cool",
                      "bleach",
                      "vivid",
                      "noir",
                      "night"
                    ],
                    "description": "timeline: the colour grade over every cut. none if left out."
                  },
                  "grain": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 20,
                    "description": "timeline: film grain. Grain makes the file larger."
                  },
                  "vignette": {
                    "type": "boolean",
                    "description": "timeline: darken the corners a little."
                  },
                  "subtitles": {
                    "type": "string",
                    "description": "timeline: an ASS lyrics file as text, up to 2 MB."
                  },
                  "subtitlesUrl": {
                    "type": "string",
                    "format": "uri",
                    "description": "timeline: a link to an ASS lyrics file, such as a POST /uploads url (contentType text/x-ssa)."
                  },
                  "subtitlesOffsetSeconds": {
                    "type": "number",
                    "minimum": 0,
                    "description": "timeline: where this render starts in the song, so the lyrics line up."
                  },
                  "audioUrl": {
                    "type": "string",
                    "format": "uri",
                    "description": "timeline or join: a sound file to lay under the result."
                  },
                  "audioStartSeconds": {
                    "type": "number",
                    "minimum": 0,
                    "description": "timeline or join: where in the sound file to start."
                  },
                  "fadeInSeconds": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 5,
                    "description": "timeline: fade in from black at the start."
                  },
                  "fadeOutSeconds": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 5,
                    "description": "timeline: fade out to black at the end."
                  },
                  "idempotencyKey": {
                    "type": "string",
                    "maxLength": 255,
                    "description": "Same as the Idempotency-Key header, for clients that cannot set headers."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "The edit started",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "jobId": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        },
                        "operation": {
                          "type": "string"
                        },
                        "creditsCharged": {
                          "type": "integer"
                        },
                        "pollUrl": {
                          "type": "string"
                        },
                        "replayed": {
                          "type": "boolean",
                          "description": "Present and true only when this answer was replayed for a repeated Idempotency-Key. The jobId is the original job's and nothing was charged again."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or malformed fields (invalid_request). timeline also answers too_long (over 60 seconds: render in parts and join them), source_not_found (a job id that is not this key's) and source_not_ready (a job that has not finished).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "402": {
            "$ref": "#/components/responses/InsufficientCredits"
          },
          "409": {
            "$ref": "#/components/responses/RequestInFlight"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "description": "That is a lot of edits in one hour. Try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/videos/edits/{jobId}": {
      "get": {
        "tags": [
          "Videos"
        ],
        "summary": "Read a video edit job",
        "description": "Once completed the result has a download link good for an hour; poll again for a fresh one. A frame comes back under image (a JPEG), everything else under video (an MP4). A failed edit refunds its credits on the first read.",
        "parameters": [
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The job as it stands",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "jobId": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "pending",
                            "processing",
                            "completed",
                            "failed"
                          ]
                        },
                        "operation": {
                          "type": "string"
                        },
                        "creditsUsed": {
                          "type": "integer"
                        },
                        "creditsRefunded": {
                          "type": "integer",
                          "description": "On a failed job: what was given back."
                        },
                        "image": {
                          "type": "object",
                          "description": "frame results",
                          "properties": {
                            "url": {
                              "type": "string"
                            },
                            "bytes": {
                              "type": "integer"
                            },
                            "contentType": {
                              "type": "string"
                            },
                            "width": {
                              "type": "integer"
                            },
                            "height": {
                              "type": "integer"
                            }
                          }
                        },
                        "video": {
                          "type": "object",
                          "description": "compose, trim and audio results",
                          "properties": {
                            "url": {
                              "type": "string"
                            },
                            "bytes": {
                              "type": "integer"
                            },
                            "contentType": {
                              "type": "string"
                            },
                            "seconds": {
                              "type": "number"
                            },
                            "width": {
                              "type": "integer"
                            },
                            "height": {
                              "type": "integer"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No such job for this key"
          }
        }
      }
    },
    "/uploads": {
      "post": {
        "tags": [
          "Files"
        ],
        "summary": "Get a link to upload a file to",
        "description": "For a file on your own machine: a photo to use as a reference or first frame, a clip, or a sound file. Answers with uploadUrl, which takes one PUT of exactly bytes bytes with the Content-Type you named, and url, the link to pass to imageUrls, imageUrl, lastFrameUrl, referenceImageUrls or the video editing items once the PUT is done. uploadUrl works for 15 minutes, url for a day, and the file is deleted after a day. Free; 120 an hour per key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "contentType",
                  "bytes"
                ],
                "properties": {
                  "contentType": {
                    "type": "string",
                    "enum": [
                      "image/png",
                      "image/jpeg",
                      "image/webp",
                      "audio/mpeg",
                      "audio/mp4",
                      "audio/aac",
                      "audio/wav",
                      "audio/x-wav",
                      "audio/flac",
                      "audio/ogg",
                      "video/mp4",
                      "video/quicktime",
                      "video/webm",
                      "text/x-ssa"
                    ],
                    "description": "The file type. Pictures up to 8 MB, sound and video up to 50 MB, an ASS lyrics file (text/x-ssa) up to 2 MB."
                  },
                  "bytes": {
                    "type": "integer",
                    "minimum": 1,
                    "description": "The exact size of the file. It is signed into uploadUrl, so a PUT of any other size is refused."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Where to put the file and how to use it",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "uploadUrl": {
                          "type": "string"
                        },
                        "method": {
                          "type": "string",
                          "enum": [
                            "PUT"
                          ]
                        },
                        "headers": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "string"
                          },
                          "description": "Send these with the PUT."
                        },
                        "curl": {
                          "type": "string",
                          "description": "A ready command; put your file path in place of FILE."
                        },
                        "url": {
                          "type": "string",
                          "description": "The file once uploaded. Works for a day."
                        },
                        "kind": {
                          "type": "string",
                          "enum": [
                            "image",
                            "audio",
                            "video",
                            "subtitles"
                          ]
                        },
                        "contentType": {
                          "type": "string"
                        },
                        "bytes": {
                          "type": "integer"
                        },
                        "uploadExpiresAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "urlExpiresAt": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "bytes is missing or not a whole number (bad_request), or contentType is not one we take (unsupported_media_type).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/credits": {
      "get": {
        "tags": [
          "Credits"
        ],
        "summary": "Read the credit balance",
        "description": "What the account can spend. Spend against total: the buckets are drawn down in spendOrder, so on an active subscription the monthly allowance goes first and the daily free grant is untouched until it runs out. Do not treat free as the budget. Free to call.",
        "responses": {
          "200": {
            "description": "The balance",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "total": {
                          "type": "integer",
                          "description": "What you can spend."
                        },
                        "subscription": {
                          "type": "integer"
                        },
                        "paid": {
                          "type": "integer"
                        },
                        "free": {
                          "type": "integer"
                        },
                        "subscriptionActive": {
                          "type": "boolean"
                        },
                        "spendOrder": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "The order the buckets are drawn down in."
                        },
                        "note": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    }
  }
}
