{"openapi":"3.1.0","info":{"title":"Adwright API","version":"1.0.0","description":"Researched image and video ads, the Ad Council, and the models behind them. Authenticate with `Authorization: Bearer adw_live_…`."},"servers":[{"url":"https://api.adwright.co/v1/platform"}],"security":[{"bearer":[]}],"tags":[{"name":"Models","description":"Every image and video model, and Adwright's own workflows, with what each costs on your account."},{"name":"Generations","description":"One request, one model, one picture or clip (or up to eight at once). Give pictures and clips to work from by uploading them first."},{"name":"Workflows","description":"What only Adwright does. A project reads a link (a website, store, product page or app), researches the product, its audience and its competitors, finds the angles and makes its first image ads. More ads, video ads and the Ad Council build on it."},{"name":"Jobs and balance","description":"Every request that starts work makes a job: its status and its webhook's, in one place."}],"paths":{"/models":{"get":{"operationId":"list-models","summary":"List models","description":"The catalogue, most used first. Models' price_from is one generation at their defaults; workflows' is the cheapest way to run them.","tags":["Models"],"parameters":[{"name":"type","in":"query","required":false,"description":"image, video or workflow: only that kind.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":[{"id":"gw:openai/gpt-image-2.5-flare","object":"model","type":"image","name":"GPT Image 2.5","variant":"","maker":"openai","description":"Sharp, legible type and faithful product shots.","does":["text to image","edit"],"unit":"image","price_from":{"usd":0.05},"popular_rank":1,"inputs":{"images":4,"aspects":["1:1","4:5","9:16","16:9"],"resolutions":["2k","4k"]}},{"id":"workflow/project","object":"model","type":"workflow","name":"Project from a link","unit":"project","price_from":{"usd":1.1}}]}}}},"default":{"description":"A refusal","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/generations":{"post":{"operationId":"create-generation","summary":"Create a generation","description":"Starts count generations on a model. Each is charged its exact price when it starts and refunded if it fails.","tags":["Generations"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"model":{"type":"string","description":"A model id from GET /models."},"prompt":{"type":"string","description":"What to make."},"aspect":{"type":"string","description":"1:1, 4:5, 9:16, 16:9… as the model's inputs.aspects list. Pictures default to 1:1, clips to 9:16."},"inputs":{"type":"object","description":"duration, resolution, quality, sound, negative, seed, and upload ids: start, end, images[], videos[]."},"count":{"type":"integer","description":"1 to 8 (default 1). All or none: if the balance can't cover them all, none start."},"webhook_url":{"type":"string","description":"An https address to POST the outcome to when it finishes. See Webhooks."}},"required":["model"]},"example":{"model":"gw:openai/gpt-image-2.5-flare","prompt":"A glass serum bottle on wet black stone, morning light","aspect":"4:5","count":2}}}},"responses":{"202":{"description":"OK","content":{"application/json":{"example":{"data":[{"id":"med_8f2c1a9e4b7d3f60a1c2","object":"generation","job_id":"job_4a1f9c2e7b3d8e6f0a1b","model":"gw:openai/gpt-image-2.5-flare","type":"image","status":"queued","prompt":"A glass serum bottle on wet black stone, morning light","aspect":"4:5","output":null,"error":null,"cost":{"usd":0.052},"created_at":"2026-10-29T09:41:00Z","completed_at":null}]}}}},"default":{"description":"A refusal","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"get":{"operationId":"list-generations","summary":"List generations","description":"The ones your keys made, newest first.","tags":["Generations"],"parameters":[{"name":"limit","in":"query","required":false,"description":"1 to 100 (default 20).","schema":{"type":"integer"}},{"name":"before","in":"query","required":false,"description":"A generation id: the page after it.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":[{"id":"med_8f2c1a9e4b7d3f60a1c2","object":"generation","job_id":"job_4a1f9c2e7b3d8e6f0a1b","model":"gw:openai/gpt-image-2.5-flare","type":"image","status":"succeeded","prompt":"A glass serum bottle on wet black stone, morning light","aspect":"4:5","output":{"url":"https://adwright.co/media/med_8f2c1a9e4b7d3f60a1c2.png","content_type":"image/png"},"error":null,"cost":{"usd":0.052},"created_at":"2026-10-29T09:41:00Z","completed_at":"2026-10-29T09:41:24Z"}],"has_more":false}}}},"default":{"description":"A refusal","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/generations/quote":{"post":{"operationId":"quote-generation","summary":"Price a generation","description":"What the same request would cost, and whether your balance covers it. Nothing is made or charged.","tags":["Generations"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"model":{"type":"string","description":"A model id."},"prompt":{"type":"string","description":"As for a generation."},"aspect":{"type":"string","description":"As for a generation."},"inputs":{"type":"object","description":"As for a generation: the length and resolution change the price."},"count":{"type":"integer","description":"1 to 8."}},"required":["model"]},"example":{"model":"kling-video/v3.0/std/image-to-video","inputs":{"duration":5},"count":1}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"model":"kling-video/v3.0/std/image-to-video","each":{"usd":0.42},"total":{"usd":0.42},"affordable":true,"missing":"a start image"}}}},"default":{"description":"A refusal","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/generations/{id}":{"get":{"operationId":"get-generation","summary":"Retrieve a generation","description":"Where it's got to. When status is succeeded, output.url is the file.","tags":["Generations"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"id":"med_8f2c1a9e4b7d3f60a1c2","object":"generation","job_id":"job_4a1f9c2e7b3d8e6f0a1b","model":"gw:openai/gpt-image-2.5-flare","type":"image","status":"succeeded","prompt":"A glass serum bottle on wet black stone, morning light","aspect":"4:5","output":{"url":"https://adwright.co/media/med_8f2c1a9e4b7d3f60a1c2.png","content_type":"image/png"},"error":null,"cost":{"usd":0.052},"created_at":"2026-10-29T09:41:00Z","completed_at":"2026-10-29T09:41:24Z"}}}},"default":{"description":"A refusal","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/uploads":{"post":{"operationId":"upload","summary":"Upload a file","description":"A picture (PNG, JPEG, WebP, GIF, up to 30 MB) or a clip (MP4, MOV, WebM, up to 100 MB) to make from. Send it as multipart/form-data, field file.","tags":["Generations"],"parameters":[],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}},"required":["file"]}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"example":{"id":"med_1c9e7a3f5b2d8e4a6c0f","object":"upload","type":"image","content_type":"image/jpeg","url":"https://adwright.co/media/med_1c9e7a3f5b2d8e4a6c0f.jpg","created_at":"2026-10-29T09:41:00Z"}}}},"default":{"description":"A refusal","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects":{"post":{"operationId":"create-project","summary":"Start a project","description":"Research and the first ads take a few minutes. The project's status is succeeded once its ads are made.","tags":["Workflows"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"The link to start from. Required unless you send a brief."},"brief":{"type":"string","description":"What the product is, who it's for, what to focus on."},"platforms":{"type":"array","items":{"type":"string"},"description":"Any of meta, stories, tiktok, linkedin, google, x, pinterest (default: meta, stories, tiktok)."},"language":{"type":"string","description":"Write the ads in this language (default: the site's own)."},"research":{"type":"string","description":"sharp or frontier: the research mode, at its flat price."},"webhook_url":{"type":"string","description":"An https address to POST the outcome to when it finishes. See Webhooks."}},"required":[]},"example":{"url":"https://example.com/products/serum","platforms":["meta","tiktok"],"research":"sharp","webhook_url":"https://example.com/hooks/adwright"}}}},"responses":{"202":{"description":"OK","content":{"application/json":{"example":{"id":"prj_5d2a8c1e9f3b","object":"project","name":"Example Serum","url":"https://example.com/products/serum","status":"queued","stage":"queued","progress":0,"ads":0,"created_at":"2026-10-29T09:41:00Z","updated_at":"2026-10-29T09:41:00Z"}}}},"default":{"description":"A refusal","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"get":{"operationId":"list-projects","summary":"List projects","description":"Newest first.","tags":["Workflows"],"parameters":[{"name":"limit","in":"query","required":false,"description":"1 to 100 (default 20).","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":[{"id":"prj_5d2a8c1e9f3b","object":"project","name":"Example Serum","status":"succeeded","ads":6}],"has_more":false}}}},"default":{"description":"A refusal","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{id}":{"get":{"operationId":"get-project","summary":"Retrieve a project","description":"Its research (the product, who it's for, the angles), its image ads with their copy and pictures, and its videos.","tags":["Workflows"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"id":"prj_5d2a8c1e9f3b","object":"project","name":"Example Serum","status":"succeeded","product":{"name":"Example Serum","one_liner":"A vitamin C serum for dull skin","audience":["Women 25-40 with dull skin"]},"angles":[{"key":"glow-fast","name":"Visible glow in a week"}],"ads":[{"id":"cre_9a1f","platform":"meta","aspect":"4:5","angle":"glow-fast","headline":"Glow by Friday","primary_text":"…","image_url":"https://adwright.co/media/….png"}],"videos":[]}}}},"default":{"description":"A refusal","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{id}/ads":{"post":{"operationId":"create-ads","summary":"Make more image ads","description":"Written for the project's angles and drawn in its brand. Follow the job; the ads appear on the project.","tags":["Workflows"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer","description":"1 to 8 (default 4)."},"platform":{"type":"string","description":"Where they'll run (default: the project's platforms)."},"angle":{"type":"string","description":"An angle's key from the project, to write them all for it."},"instruction":{"type":"string","description":"Anything to steer them: a message, an offer, a look."},"webhook_url":{"type":"string","description":"An https address to POST the outcome to when it finishes. See Webhooks."}},"required":[]},"example":{"count":4,"platform":"meta","angle":"glow-fast","instruction":"Lead with the 20% launch offer"}}}},"responses":{"202":{"description":"OK","content":{"application/json":{"example":{"id":"job_7c3e9a1f2b4d6e8a0c1f","object":"job","kind":"ads","status":"running","target_id":"sjb_2b9e4c1a7f3d","project_id":"prj_5d2a8c1e9f3b","video_ids":null,"ads_requested":4,"created_at":"2026-10-29T09:41:00Z","finished_at":null,"webhook":{"url":"https://example.com/hooks/adwright","delivered_at":null,"attempts":0,"last_error":null}}}}},"default":{"description":"A refusal","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/video-styles":{"get":{"operationId":"video-styles","summary":"List video styles","description":"The styles videos are made in (claymation, 3D, talking heads, podcasts, UGC…) and what one costs at each length.","tags":["Workflows"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":[{"id":"claymation","label":"Claymation","description":"A stop-motion clay story…","family":"animated","seconds":[15,30],"price_by_seconds":{"15":{"usd":4.1},"30":{"usd":7.2}}}],"lengths":[15,30,45,60]}}}},"default":{"description":"A refusal","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/projects/{id}/videos":{"post":{"operationId":"create-videos","summary":"Make video ads","description":"Written from the project's research, made scene by scene, edited and closed on the brand's end card. Several minutes each.","tags":["Workflows"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"style":{"type":"string","description":"A style id from GET /video-styles."},"seconds":{"type":"integer","description":"15, 30, 45 or 60 (default 30)."},"count":{"type":"integer","description":"1 to 4 (default 1)."},"aspect":{"type":"string","description":"9:16 (default), 4:5 or 1:1."},"angle":{"type":"string","description":"An angle's key from the project."},"instruction":{"type":"string","description":"A message, an offer, a story idea."},"webhook_url":{"type":"string","description":"An https address to POST the outcome to when it finishes. See Webhooks."}},"required":["style"]},"example":{"style":"claymation","seconds":30,"count":1,"aspect":"9:16"}}}},"responses":{"202":{"description":"OK","content":{"application/json":{"example":{"job":{"id":"job_7c3e9a1f2b4d6e8a0c1f","object":"job","kind":"videos","status":"running","target_id":"prj_5d2a8c1e9f3b","project_id":"prj_5d2a8c1e9f3b","video_ids":["vid_3e8a1c"],"ads_requested":null,"created_at":"2026-10-29T09:41:00Z","finished_at":null,"webhook":{"url":"https://example.com/hooks/adwright","delivered_at":null,"attempts":0,"last_error":null}},"videos":[{"id":"vid_3e8a1c","object":"video","status":"running","style":"claymation"}]}}}},"default":{"description":"A refusal","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/videos/{id}":{"get":{"operationId":"get-video","summary":"Retrieve a video","description":"Its status, length and thumbnail. Render it to get one MP4.","tags":["Workflows"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"id":"vid_3e8a1c","object":"video","project_id":"prj_5d2a8c1e9f3b","title":"Glow by Friday","style":"claymation","aspect":"9:16","status":"succeeded","seconds":29.6,"thumbnail_url":"https://adwright.co/media/….jpg"}}}},"default":{"description":"A refusal","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/videos/{id}/render":{"post":{"operationId":"render-video","summary":"Render a video to MP4","description":"Renders a finished video to one MP4 on our side. Read it with GET /videos/{id}/render until it has a url.","tags":["Workflows"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"202":{"description":"OK","content":{"application/json":{"example":{"id":"rnd_6b1e","object":"render","video_id":"vid_3e8a1c","status":"rendering","progress":10,"url":null,"error":null,"stale":false}}}},"default":{"description":"A refusal","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/council":{"post":{"operationId":"ask-council","summary":"Ask the Ad Council","description":"Seven ad experts read the market and the ads winning in it, argue it out and give a verdict: which angle, whether to launch, what to change.","tags":["Workflows"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"question":{"type":"string","description":"The question, in a sentence or two."},"project_id":{"type":"string","description":"A project, so the council knows the product and its market."},"options":{"type":"array","items":{"type":"string"},"description":"Two to five options to choose between."},"webhook_url":{"type":"string","description":"An https address to POST the outcome to when it finishes. See Webhooks."}},"required":["question"]},"example":{"question":"Which angle should we launch with?","project_id":"prj_5d2a8c1e9f3b","options":["Visible glow in a week","Dermatologist-made"]}}}},"responses":{"202":{"description":"OK","content":{"application/json":{"example":{"id":"cs_2f8e1a","object":"council","question":"Which angle should we launch with?","status":"queued","verdict":null}}}},"default":{"description":"A refusal","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/council/{id}":{"get":{"operationId":"get-council","summary":"Read the council's verdict","description":"Once status is succeeded: what it recommends, how sure it is, why, and the next steps.","tags":["Workflows"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"id":"cs_2f8e1a","object":"council","status":"succeeded","verdict":{"recommended":"Visible glow in a week","band":"strong","confidence":0.78,"summary":"…","next_steps":["…"]}}}}},"default":{"description":"A refusal","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/jobs/{id}":{"get":{"operationId":"get-job","summary":"Retrieve a job","description":"queued, running, succeeded or failed, what it made, and how its webhook went.","tags":["Jobs and balance"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"id":"job_7c3e9a1f2b4d6e8a0c1f","object":"job","kind":"ads","status":"succeeded","target_id":"sjb_2b9e4c1a7f3d","project_id":"prj_5d2a8c1e9f3b","video_ids":null,"ads_requested":4,"created_at":"2026-10-29T09:41:00Z","finished_at":"2026-10-29T09:44:10Z","webhook":{"url":"https://example.com/hooks/adwright","delivered_at":null,"attempts":0,"last_error":null}}}}},"default":{"description":"A refusal","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/balance":{"get":{"operationId":"get-balance","summary":"Retrieve the balance","description":"What the next request can spend, and what running work holds.","tags":["Jobs and balance"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"object":"balance","available":{"usd":48.32},"held":{"usd":0.42}}}}},"default":{"description":"A refusal","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer"}},"schemas":{"Problem":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string","enum":["invalid_request","unauthorized","insufficient_balance","forbidden","not_found","conflict","idempotency_conflict","too_large","rate_limited","concurrency_limited","unavailable","server_error"]},"detail":{"type":"string"},"request_id":{"type":"string"}},"required":["title","status","code"]}}}}