{"openapi":"3.1.0","info":{"title":"AirGraphic API","version":"2026-05-19","description":"Generate on-brand infographics from URLs, text, PDFs, slide decks, and images."},"servers":[{"url":"https://airgraphic.io","description":"Production"},{"url":"http://localhost:3000","description":"Local development"}],"tags":[{"name":"Generations","description":"Create and poll infographic jobs."},{"name":"Brands","description":"Preview brand identity from a public website."}],"paths":{"/api/generate":{"post":{"tags":["Generations"],"summary":"Create a generation","description":"Queues one infographic generation. The response returns a job id immediately; poll /api/jobs/{id} for completion.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateRequest"},"examples":{"url":{"summary":"Generate from a URL","value":{"sourceUrl":"https://example.com/blog/post","aspectRatio":"4:5","outputFormat":"png","outcome":"linkedin_carousel_slide"}},"text":{"summary":"Generate from pasted text","value":{"sourceText":"Three launch lessons: keep scope narrow, show real examples, and make sharing easy.","aspectRatio":"1:1","outputFormat":"png"}}}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/GenerateMultipartRequest"}}}},"responses":{"202":{"description":"Generation queued.","headers":{"x-ratelimit-limit":{"schema":{"type":"integer"}},"x-ratelimit-remaining":{"schema":{"type":"integer"}},"x-ratelimit-reset":{"schema":{"type":"string","format":"date-time"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateQueued"}}}},"400":{"description":"Invalid or unsupported source input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, revoked, or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Workspace has no credits remaining.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Plan rate limit reached.","headers":{"x-ratelimit-limit":{"schema":{"type":"integer"}},"x-ratelimit-remaining":{"schema":{"type":"integer"}},"x-ratelimit-reset":{"schema":{"type":"string","format":"date-time"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"502":{"description":"A provider failed after the job was accepted; the credit is refunded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/jobs/{id}":{"get":{"tags":["Generations"],"summary":"Get a generation job","description":"Returns the current job state. Queued or running jobs are advanced by polling the image provider.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Current job state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"401":{"description":"Missing, revoked, or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No generation exists in the authenticated workspace for this id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/brand-preview":{"get":{"tags":["Brands"],"summary":"Preview a brand URL","description":"Extracts public logo, palette, and font hints from a brand website.","parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","format":"uri"}}],"responses":{"200":{"description":"Brand preview.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandPreview"}}}},"400":{"description":"Missing or invalid URL.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"ag_ API key","x-default":"ag_your_api_key"}},"schemas":{"GenerateRequest":{"type":"object","additionalProperties":false,"properties":{"sourceUrl":{"type":"string","format":"uri"},"sourceText":{"type":"string","maxLength":8000},"sourceImage":{"type":"string","description":"PNG, JPG, or WebP data URI used as the primary source."},"brandUrl":{"type":"string","format":"uri"},"aspectRatio":{"type":"string","enum":["9:16","1:1","4:5","16:9"],"default":"9:16"},"outputFormat":{"type":"string","enum":["png","jpeg","webp"],"default":"png"},"fontName":{"type":"string","maxLength":80},"fontCssUrl":{"type":"string","format":"uri"},"styleNotes":{"type":"string","maxLength":800},"enableCritique":{"type":"boolean","default":false},"referenceImage":{"type":"string","description":"Optional http(s) image URL or data URI for visual style or asset guidance."},"referenceNote":{"type":"string","maxLength":500},"brandProfileId":{"type":"string","format":"uuid"},"outcome":{"type":"string","enum":["linkedin_carousel_slide","linkedin_post","instagram_post","story_reel","blog_header","custom"]}},"oneOf":[{"required":["sourceUrl"]},{"required":["sourceText"]},{"required":["sourceImage"]}]},"GenerateMultipartRequest":{"type":"object","properties":{"params":{"type":"string","description":"JSON-encoded GenerateRequest fields."},"referenceImage":{"type":"string","format":"binary","description":"Optional PNG/JPG/WebP/GIF/BMP reference image."},"sourcePdf":{"type":"string","format":"binary","description":"Optional PDF primary source, max 15 MB."},"sourcePptx":{"type":"string","format":"binary","description":"Optional PPTX primary source, max 25 MB."},"sourceImage":{"type":"string","format":"binary","description":"Optional image primary source, max 8 MB."}}},"GenerateQueued":{"type":"object","required":["jobId","status","stages"],"properties":{"jobId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued"]},"falRequestId":{"type":"string"},"stages":{"type":"array","items":{"type":"string"}}}},"Job":{"type":"object","required":["id","status","sourceUrl","aspect","format","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","running","completed","failed","refunded"]},"sourceUrl":{"type":"string"},"aspect":{"type":"string","enum":["9:16","1:1","4:5","16:9"]},"format":{"type":"string","enum":["png","jpeg","webp"]},"imageUrl":{"type":"string","format":"uri"},"falImageUrl":{"type":"string","format":"uri"},"mirrorUrl":{"type":"string","format":"uri"},"width":{"type":"integer"},"height":{"type":"integer"},"contentType":{"type":"string"},"prompt":{"type":"string"},"error":{"type":"string"},"falRequestId":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"}}},"BrandPreview":{"type":"object","properties":{"fonts":{"type":"array","items":{"type":"string"}},"primaryFont":{"type":"string"},"logo":{"type":"string","format":"uri"},"palette":{"type":"array","items":{"type":"string"}}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"code":{"type":"string"}}},"RateLimitError":{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"bucket":{"type":"string"},"count":{"type":"integer"},"limit":{"type":"integer"},"resetAt":{"type":"string","format":"date-time"}}}]}}}}