{"openapi":"3.1.0","info":{"title":"Imaginou API","version":"2026-10-25","description":"Create and review AI product videos from a product link or product photos. Authenticate with a personal access token from the studio (Connect AI) or through OAuth 2.1 (see /.well-known/oauth-authorization-server). The same capabilities are available to AI agents through the MCP endpoint at https://app.imaginou.com/mcp.","contact":{"name":"Imaginou","url":"https://app.imaginou.com/developers","email":"contact@imaginou.com"}},"servers":[{"url":"https://app.imaginou.com/api/v1"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"imk_…","description":"Personal access token or OAuth access token."}},"schemas":{"Production":{"type":"object","description":"A production (order) owned by the authenticated account.","properties":{"id":{"type":"string"},"state":{"type":"string","enum":["queued_import","importing","queued_images","generating_images","awaiting_approval","awaiting_changes","queued_videos","generating_videos","queued_finish","editing","queued_quality","checking_quality","quality_hold","awaiting_soundtrack","awaiting_final_review","completed","failed","storage_full","cancelled"]},"status":{"type":"object","properties":{"phase":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"},"requiresAction":{"type":"boolean"},"suggestedTools":{"type":"array","items":{"type":"string"}},"waiting":{"type":"boolean"}}},"workflow":{"type":"string","enum":["showroom","influencer","viral"]},"language":{"type":"string"},"productUrl":{"type":["string","null"]},"title":{"type":"string"},"brief":{"type":"string"},"revision":{"type":"integer"},"storyboardFingerprint":{"type":["string","null"]},"videoFingerprint":{"type":["string","null"]},"storyboardChanges":{"type":["object","null"]},"storyboard":{"type":["object","null"]},"deliverables":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"music":{"type":["object","null"]},"error":{"type":["string","null"]}}},"Media":{"type":"object","properties":{"mediaId":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string"},"mime":{"type":"string"},"url":{"type":"string","description":"Signed link valid for one hour; no Authorization header needed."},"apiUrl":{"type":"string","description":"Bearer-authenticated file endpoint."},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"durationSeconds":{"type":["number","null"]}}},"CreateProduction":{"type":"object","required":["workflow"],"properties":{"productUrl":{"type":"string","format":"uri"},"workflow":{"type":"string","enum":["showroom","influencer","viral"]},"language":{"type":"string","enum":["en","fr","pt","es"],"default":"en"},"brief":{"type":"string","maxLength":4000},"manual":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"}}},"photos":{"type":"array","maxItems":8,"items":{"type":"object","properties":{"base64":{"type":"string"},"mime":{"type":"string"},"name":{"type":"string"},"mediaId":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"clientRequestId":{"type":"string","format":"uuid","description":"Stable idempotency key; repeat it to retry safely."}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}},"paths":{"/capabilities":{"get":{"summary":"What Imaginou can do (public)","tags":["Discovery"],"responses":{"200":{"description":"OK"}}}},"/me":{"get":{"summary":"Account, credits, storage and productions needing attention","tags":["Account"],"security":[{"bearerAuth":[]}],"x-scope":"account:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid bearer token"},"403":{"description":"Token lacks the required scope"},"404":{"description":"Not found or owned by another account"},"409":{"description":"The production is not in a state that allows this action"}}}},"/productions":{"get":{"summary":"List productions","tags":["Productions"],"security":[{"bearerAuth":[]}],"x-scope":"productions:read","parameters":[{"name":"state","in":"query","schema":{"type":"string"},"description":"Comma-separated states or phases (storyboard, video, review, music, done, attention)."},{"name":"limit","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"productions":{"type":"array","items":{"$ref":"#/components/schemas/Production"}}}}}}},"401":{"description":"Missing or invalid bearer token"},"403":{"description":"Token lacks the required scope"},"404":{"description":"Not found or owned by another account"},"409":{"description":"The production is not in a state that allows this action"}}},"post":{"summary":"Create a production from a product link or manual details + photos","tags":["Productions"],"security":[{"bearerAuth":[]}],"x-scope":"productions:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProduction"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Production"}}}},"401":{"description":"Missing or invalid bearer token"},"403":{"description":"Token lacks the required scope"},"404":{"description":"Not found or owned by another account"},"409":{"description":"The production is not in a state that allows this action"}}}},"/productions/{id}":{"get":{"summary":"Production details with storyboard, media links and review findings","tags":["Productions"],"security":[{"bearerAuth":[]}],"x-scope":"productions:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Production"}}}},"401":{"description":"Missing or invalid bearer token"},"403":{"description":"Token lacks the required scope"},"404":{"description":"Not found or owned by another account"},"409":{"description":"The production is not in a state that allows this action"}}}},"/productions/{id}/wait":{"get":{"summary":"Long-poll until the production needs attention or a state is reached (≤55 s)","tags":["Productions"],"security":[{"bearerAuth":[]}],"x-scope":"productions:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"timeoutMs","in":"query","schema":{"type":"integer"}},{"name":"until","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid bearer token"},"403":{"description":"Token lacks the required scope"},"404":{"description":"Not found or owned by another account"},"409":{"description":"The production is not in a state that allows this action"}}}},"/productions/{id}/approve":{"post":{"summary":"Approve the storyboard and queue video generation","tags":["Productions"],"security":[{"bearerAuth":[]}],"x-scope":"productions:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"acceptFindings":{"type":"boolean"},"fingerprint":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Production"}}}},"401":{"description":"Missing or invalid bearer token"},"403":{"description":"Token lacks the required scope"},"404":{"description":"Not found or owned by another account"},"409":{"description":"The production is not in a state that allows this action"}}}},"/productions/{id}/changes":{"post":{"summary":"Request storyboard changes (uses an included change or, with consumeCredit, one credit)","tags":["Productions"],"security":[{"bearerAuth":[]}],"x-scope":"productions:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["scenes","notes"],"properties":{"scenes":{"type":"array","items":{"type":"string","enum":["scene-1","scene-2","scene-3"]}},"notes":{"type":"string","minLength":15,"maxLength":2000},"consumeCredit":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Production"}}}},"401":{"description":"Missing or invalid bearer token"},"403":{"description":"Token lacks the required scope"},"404":{"description":"Not found or owned by another account"},"409":{"description":"The production is not in a state that allows this action"}}}},"/productions/{id}/review":{"post":{"summary":"Approve or reject the generated video","tags":["Productions"],"security":[{"bearerAuth":[]}],"x-scope":"productions:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["decision"],"properties":{"decision":{"type":"string","enum":["approve","reject"]}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Production"}}}},"401":{"description":"Missing or invalid bearer token"},"403":{"description":"Token lacks the required scope"},"404":{"description":"Not found or owned by another account"},"409":{"description":"The production is not in a state that allows this action"}}}},"/productions/{id}/music":{"post":{"summary":"Choose soundtrack A, B or none","tags":["Productions"],"security":[{"bearerAuth":[]}],"x-scope":"productions:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["choice"],"properties":{"choice":{"type":"string","enum":["A","B","none"]}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Production"}}}},"401":{"description":"Missing or invalid bearer token"},"403":{"description":"Token lacks the required scope"},"404":{"description":"Not found or owned by another account"},"409":{"description":"The production is not in a state that allows this action"}}}},"/productions/{id}/edit":{"post":{"summary":"Re-edit pacing, sound effects and polished text without regenerating footage","tags":["Productions"],"security":[{"bearerAuth":[]}],"x-scope":"productions:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"trimSilence":{"type":"boolean"},"soundEffects":{"type":"boolean"},"polishedOverlays":{"type":"boolean"},"notes":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Production"}}}},"401":{"description":"Missing or invalid bearer token"},"403":{"description":"Token lacks the required scope"},"404":{"description":"Not found or owned by another account"},"409":{"description":"The production is not in a state that allows this action"}}}},"/productions/{id}/complete":{"post":{"summary":"Mark the production complete after final playback review","tags":["Productions"],"security":[{"bearerAuth":[]}],"x-scope":"productions:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"acceptFindings":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Production"}}}},"401":{"description":"Missing or invalid bearer token"},"403":{"description":"Token lacks the required scope"},"404":{"description":"Not found or owned by another account"},"409":{"description":"The production is not in a state that allows this action"}}}},"/productions/{id}/retry":{"post":{"summary":"Authorize resuming a failed production","tags":["Productions"],"security":[{"bearerAuth":[]}],"x-scope":"productions:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Production"}}}},"401":{"description":"Missing or invalid bearer token"},"403":{"description":"Token lacks the required scope"},"404":{"description":"Not found or owned by another account"},"409":{"description":"The production is not in a state that allows this action"}}}},"/productions/{id}/cancel":{"post":{"summary":"Cancel a production (media retained)","tags":["Productions"],"security":[{"bearerAuth":[]}],"x-scope":"productions:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Production"}}}},"401":{"description":"Missing or invalid bearer token"},"403":{"description":"Token lacks the required scope"},"404":{"description":"Not found or owned by another account"},"409":{"description":"The production is not in a state that allows this action"}}}},"/productions/{id}/remove":{"post":{"summary":"Move a finished/failed production to Removed","tags":["Productions"],"security":[{"bearerAuth":[]}],"x-scope":"productions:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Production"}}}},"401":{"description":"Missing or invalid bearer token"},"403":{"description":"Token lacks the required scope"},"404":{"description":"Not found or owned by another account"},"409":{"description":"The production is not in a state that allows this action"}}}},"/productions/{id}/restore":{"post":{"summary":"Restore a removed production","tags":["Productions"],"security":[{"bearerAuth":[]}],"x-scope":"productions:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Production"}}}},"401":{"description":"Missing or invalid bearer token"},"403":{"description":"Token lacks the required scope"},"404":{"description":"Not found or owned by another account"},"409":{"description":"The production is not in a state that allows this action"}}}},"/productions/{id}/quality-check":{"post":{"summary":"Re-run the saved-footage continuity check (no generation)","tags":["Productions"],"security":[{"bearerAuth":[]}],"x-scope":"productions:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Production"}}}},"401":{"description":"Missing or invalid bearer token"},"403":{"description":"Token lacks the required scope"},"404":{"description":"Not found or owned by another account"},"409":{"description":"The production is not in a state that allows this action"}}}},"/productions/{id}/shares":{"get":{"summary":"List public share links","tags":["Sharing"],"security":[{"bearerAuth":[]}],"x-scope":"sharing:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid bearer token"},"403":{"description":"Token lacks the required scope"},"404":{"description":"Not found or owned by another account"},"409":{"description":"The production is not in a state that allows this action"}}},"post":{"summary":"Create a public share link for a finished video","tags":["Sharing"],"security":[{"bearerAuth":[]}],"x-scope":"sharing:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mediaId":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid bearer token"},"403":{"description":"Token lacks the required scope"},"404":{"description":"Not found or owned by another account"},"409":{"description":"The production is not in a state that allows this action"}}}},"/shares/{token}/revoke":{"post":{"summary":"Revoke a public share link","tags":["Sharing"],"security":[{"bearerAuth":[]}],"x-scope":"sharing:write","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid bearer token"},"403":{"description":"Token lacks the required scope"},"404":{"description":"Not found or owned by another account"},"409":{"description":"The production is not in a state that allows this action"}}}},"/media":{"get":{"summary":"List saved media (images, videos, soundtracks)","tags":["Media"],"security":[{"bearerAuth":[]}],"x-scope":"media:read","parameters":[{"name":"type","in":"query","schema":{"type":"string","enum":["image","video","audio"]}},{"name":"productionId","in":"query","schema":{"type":"string"}},{"name":"folderId","in":"query","schema":{"type":"string"}},{"name":"search","in":"query","schema":{"type":"string"}},{"name":"trash","in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"media":{"type":"array","items":{"$ref":"#/components/schemas/Media"}}}}}}},"401":{"description":"Missing or invalid bearer token"},"403":{"description":"Token lacks the required scope"},"404":{"description":"Not found or owned by another account"},"409":{"description":"The production is not in a state that allows this action"}}},"post":{"summary":"Organize media: move, rename, trash, restore or delete","tags":["Media"],"security":[{"bearerAuth":[]}],"x-scope":"media:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action","mediaIds"],"properties":{"action":{"type":"string","enum":["move","rename","trash","restore","delete"]},"mediaIds":{"type":"array","items":{"type":"string"}},"folderId":{"type":["string","null"]},"name":{"type":"string"},"confirmPermanent":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid bearer token"},"403":{"description":"Token lacks the required scope"},"404":{"description":"Not found or owned by another account"},"409":{"description":"The production is not in a state that allows this action"}}}},"/media/{id}/file":{"get":{"summary":"Stream or download a media file (bearer token, or the signed url from any Media object)","tags":["Media"],"security":[{"bearerAuth":[]},{}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"download","in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Binary media; supports Range requests"},"206":{"description":"Partial content"}}}},"/folders":{"get":{"summary":"List library folders","tags":["Media"],"security":[{"bearerAuth":[]}],"x-scope":"media:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid bearer token"},"403":{"description":"Token lacks the required scope"},"404":{"description":"Not found or owned by another account"},"409":{"description":"The production is not in a state that allows this action"}}},"post":{"summary":"Create, rename or remove a folder","tags":["Media"],"security":[{"bearerAuth":[]}],"x-scope":"media:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["create","rename","remove"]},"name":{"type":"string"},"folderId":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid bearer token"},"403":{"description":"Token lacks the required scope"},"404":{"description":"Not found or owned by another account"},"409":{"description":"The production is not in a state that allows this action"}}}},"/billing":{"get":{"summary":"Remaining order credits and prices","tags":["Billing"],"security":[{"bearerAuth":[]}],"x-scope":"billing:read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid bearer token"},"403":{"description":"Token lacks the required scope"},"404":{"description":"Not found or owned by another account"},"409":{"description":"The production is not in a state that allows this action"}}}},"/billing/checkout":{"post":{"summary":"Create a Stripe Checkout link for a credit pack","tags":["Billing"],"security":[{"bearerAuth":[]}],"x-scope":"billing:checkout","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["plan"],"properties":{"plan":{"type":"string","enum":["single","ten","thirty"]}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid bearer token"},"403":{"description":"Token lacks the required scope"},"404":{"description":"Not found or owned by another account"},"409":{"description":"The production is not in a state that allows this action"}}}}}}