{
  "name": "Bildy Agent Manifest",
  "version": "1.4.0",
  "baseUrl": "https://bildy.ai/api/v1",
  "focus": [
    "images",
    "videos",
    "notes"
  ],
  "auth": {
    "type": "bearer",
    "header": "Authorization",
    "format": "Bearer <API_KEY>"
  },
  "responseConventions": {
    "successEnvelope": "{ data: { ... } }",
    "errorEnvelope": "{ error: { message, code } }",
    "contentType": "application/json"
  },
  "rules": [
    "Use only /api/v1 endpoints.",
    "Treat all ids as opaque strings.",
    "Generating is a job: start it, then poll its job endpoint rather than expecting the result in the first response.",
    "Download links last one hour. Poll the job again for a fresh one.",
    "Send an Idempotency-Key header (or idempotencyKey in the body) on every submit. If the answer is lost, resend with the same key: you get the same job back with no second charge, and the answer carries data.replayed: true. A 409 request_in_flight means the first is still running; wait Retry-After and resend.",
    "GET /credits before a run and spend against total. The buckets go down in spendOrder (subscription, then paid, then free), so free sitting still does not mean you are out.",
    "A request body tops out at 6 MB and inline base64 images share 5.2 MB across at most 4. Pictures already online go in imageUrls, imageUrl, lastFrameUrl or referenceImageUrls instead and skip the limit. A file on your own machine gets a link from POST /uploads.",
    "GET /images/models and GET /videos/models need no key.",
    "Each image model id makes one size. For Nano Banana 2 at 2K (2048px; GET /images/models has its price) name gemini-3.1-flash-image-2k."
  ],
  "workflows": {
    "credits": {
      "check": [
        "GET /credits, read data.total"
      ]
    },
    "images": {
      "makeOne": [
        "GET /images/models",
        "POST /images/generate with an Idempotency-Key",
        "GET /images/jobs/{jobId} until status is completed"
      ],
      "editOne": [
        "POST /images/edit with one to four images (base64) or imageUrls (links), and an Idempotency-Key",
        "GET /images/jobs/{jobId} until status is completed"
      ]
    },
    "videos": {
      "makeOne": [
        "GET /videos/models",
        "POST /videos/generate with an Idempotency-Key",
        "GET /videos/jobs/{jobId} until status is completed"
      ],
      "chainTwoClips": [
        "POST /videos/generate for the first clip, poll until completed",
        "POST /videos/edit {operation: frame, frame: last, items: [{kind: video, url: <first clip url>}]}, poll /videos/edits/{jobId}",
        "POST /videos/generate with imageUrl set to that frame's url, so the second clip starts where the first ended",
        "POST /videos/edit {operation: compose, items: [both clip urls in order]} to join them"
      ],
      "editOne": [
        "POST /videos/edit with operation frame, compose, trim, audio, timeline or join",
        "GET /videos/edits/{jobId} until status is completed"
      ],
      "storyboardVideo": [
        "POST /videos/storyboards with the prompt, the planned seconds and ratio, and any reference pictures as imageUrls",
        "GET /images/jobs/{jobId} until status is completed",
        "Show the storyboards to the person and let them pick one, or pick one yourself",
        "POST /videos/generate with the same prompt and storyboardUrl set to the chosen url, on a model whose maxReferenceImages in GET /videos/models is above 0, within the hour the link lasts",
        "GET /videos/jobs/{jobId} until status is completed"
      ],
      "animateAPicture": [
        "GET /videos/models and pick a model that takes a first frame",
        "POST /videos/generate with imageUrl set to the picture's link (an image job's url, a frame edit's url, or a POST /uploads url) and an Idempotency-Key",
        "GET /videos/jobs/{jobId} until status is completed"
      ],
      "musicVideo": [
        "POST /uploads for the song (audio/mpeg) and the ASS lyrics file (text/x-ssa), PUT each file, keep both urls",
        "For every shot: POST /images/edit for its start frame, then POST /videos/generate with imageUrl set to the frame's url; keep each clip's jobId",
        "Split the song into parts of up to 60 seconds at cut points. For each part, POST /videos/edit {operation: timeline, items: [cuts with videoJobId, seconds, startSeconds, transition], grade, subtitlesUrl, subtitlesOffsetSeconds: where the part starts}. The parts render side by side",
        "GET /videos/edits/{jobId} for each part until completed",
        "POST /videos/edit {operation: join, items: [{editJobId} for each part in order], audioUrl: the song}, then GET /videos/edits/{jobId} until completed"
      ]
    },
    "files": {
      "uploadOne": [
        "POST /uploads with contentType and the exact bytes of the file",
        "PUT the file to data.uploadUrl with the Content-Type in data.headers (data.curl is a ready command)",
        "Pass data.url wherever a link is taken: imageUrls, imageUrl, lastFrameUrl, referenceImageUrls, or an item url in /videos/edit. It works for a day"
      ]
    }
  },
  "resources": {},
  "commonErrors": [
    {
      "status": 400,
      "code": "bad_request",
      "meaning": "Missing or invalid fields."
    },
    {
      "status": 400,
      "code": "invalid_json_body",
      "meaning": "Malformed JSON body."
    },
    {
      "status": 401,
      "code": "unauthorized",
      "meaning": "Invalid or missing API key."
    },
    {
      "status": 402,
      "code": "insufficient_credits",
      "meaning": "Not enough credits for a paid endpoint. GET /credits first."
    },
    {
      "status": 409,
      "code": "request_in_flight",
      "meaning": "A submit with this Idempotency-Key is still running. Wait Retry-After seconds and resend the same request."
    },
    {
      "status": 413,
      "code": "image_too_large",
      "meaning": "Inline images are over the 5.2 MB budget. Send fewer or smaller, or use imageUrls."
    },
    {
      "status": 415,
      "code": "unsupported_media_type",
      "meaning": "Content-Type must be application/json."
    },
    {
      "status": 429,
      "code": "rate_limited",
      "meaning": "Too many requests; retry later."
    }
  ],
  "limits": {
    "imagesPerMinute": 20,
    "videosPerHour": 30,
    "videoEditsPerHour": 120,
    "otherPerMinute": 60,
    "maxRequestBodyBytes": 6291456,
    "maxInlineImageBase64Bytes": 5200000,
    "maxInputImages": 4,
    "maxImageByUrlBytes": 8250000,
    "maxVideoEditInputBytes": 52428800
  }
}
