{"openapi":"3.1.0","info":{"title":"Easymotion API","version":"1.0.0","description":"Make motion graphics videos from a prompt. Every generation renders a video file automatically, so a generation takes a few minutes: create it, then poll GET /v1/generations/{id} until status is completed. Generations use your Easymotion credits, like Studio. Motions also appear in Easymotion Studio."},"externalDocs":{"description":"Guide and examples","url":"https://easymotion.io/docs/api"},"servers":[{"url":"https://studio-be.easymotion.io/v1"}],"security":[{"apiKey":[]}],"paths":{"/generations":{"post":{"operationId":"createGeneration","summary":"Create a generation (new motion, or a new version of one)","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Retry-safe: the same key returns the first generation instead of starting another.","schema":{"type":"string","maxLength":100}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateGeneration"}}}},"responses":{"200":{"description":"Replay of an earlier request with the same Idempotency-Key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Generation"}}}},"202":{"description":"Started (status generating) or a question (status needs_input).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Generation"}}}},"400":{"description":"Invalid request (INVALID_REQUEST, INVALID_JSON).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits (INSUFFICIENT_CREDITS).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan does not include the API or this export quality.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"session_id not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The motion is still generating (ALREADY_GENERATING).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"An attachment could not be used (ATTACHMENT_FAILED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many generations running or rate limit reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listGenerations","summary":"List generations, newest first","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"before","in":"query","description":"ISO date: only generations created before it (use the last created_at for the next page).","schema":{"type":"string","format":"date-time"}},{"name":"session_id","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of generations (no signed URLs; fetch one to get them).","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Generation"}},"has_more":{"type":"boolean"}}}}}}}}},"/generations/{id}":{"get":{"operationId":"getGeneration","summary":"Get a generation (poll every 10–15 seconds)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The generation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Generation"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/generations/{id}/video":{"get":{"operationId":"downloadGenerationVideo","summary":"Download the video file (302 redirect to a fresh signed URL)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"302":{"description":"Redirect to the file."},"409":{"description":"Not ready yet, or created with export false.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"MOV file deleted after its retention period.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/account":{"get":{"operationId":"getAccount","summary":"Plan, credits and limits","responses":{"200":{"description":"The account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Authorization: Bearer em_live_… (create keys in Easymotion Studio)."}},"schemas":{"CreateGeneration":{"type":"object","required":["prompt"],"additionalProperties":false,"properties":{"prompt":{"type":"string","minLength":1,"maxLength":2000,"description":"What to make, or what to change when session_id is set. Put data in attachments, not here."},"session_id":{"type":"string","description":"Continue this motion (new version), or answer its question. Omit for a new motion."},"aspect_ratio":{"type":"string","enum":["16:9","9:16","1:1","4:5"],"description":"Default 16:9 for new motions; the motion's current shape for follow-ups."},"attachments":{"type":"array","maxItems":6,"items":{"$ref":"#/components/schemas/Attachment"}},"export":{"description":"Video file to render when the version is ready (default mp4, 30 fps, Full HD). false = no file.","oneOf":[{"type":"object","additionalProperties":false,"properties":{"format":{"type":"string","enum":["mp4","mov","gif"],"default":"mp4"},"fps":{"type":"integer","enum":[30,60],"default":30},"resolution":{"type":"string","enum":["fhd","4k"],"default":"fhd"}}},{"const":false}]},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500},"maxProperties":20,"description":"Your own key/value pairs, returned as-is."}}},"Attachment":{"type":"object","additionalProperties":false,"description":"Exactly one of url, data_base64, csv or svg.","properties":{"url":{"type":"string","format":"uri","description":"Public http(s) link to the file."},"data_base64":{"type":"string","description":"File bytes, base64. Needs filename and content_type. Up to 25 MB."},"csv":{"type":"string","description":"CSV text for a chart or table (up to 200 KB)."},"svg":{"type":"string","description":"SVG markup of a logo or icon (up to 512 KB)."},"filename":{"type":"string","maxLength":120},"content_type":{"type":"string","description":"MIME type, e.g. image/png."},"use_as":{"type":"string","enum":["style_reference","image_asset","logo_svg","data","document","video_reference"],"description":"style_reference: copy the look. image_asset: place the image in the motion. logo_svg: animate the SVG. data: chart data. document: PDF brief. video_reference: copy the motion style. Required for PNG/JPG/WebP images."},"description":{"type":"string","maxLength":500,"description":"For image_asset: what it is, e.g. \"our logo, top-left\"."},"duration_seconds":{"type":"number","maximum":60,"description":"Required for video_reference."}}},"Generation":{"type":"object","properties":{"id":{"type":"string","example":"gen_3f9a…"},"object":{"const":"generation"},"status":{"type":"string","enum":["generating","needs_input","rendering","completed","failed"]},"session_id":{"type":["string","null"]},"version":{"type":["integer","null"]},"title":{"type":["string","null"]},"prompt":{"type":"string"},"aspect_ratio":{"type":"string"},"export":{"type":["object","null"]},"studio_url":{"type":["string","null"],"description":"Open the motion in Easymotion Studio."},"progress":{"type":"object","properties":{"phase":{"type":["string","null"]},"percent":{"type":["integer","null"]},"message":{"type":["string","null"]}}},"question":{"type":"string","description":"needs_input only: answer with a new generation on the same session_id."},"video":{"type":"object","description":"completed only.","properties":{"url":{"type":"string","description":"Signed download URL, valid for 1 hour."},"url_expires_at":{"type":"string","format":"date-time"},"download_url":{"type":"string","description":"Permanent API link (needs your key) that redirects to a fresh signed URL."},"format":{"type":"string"},"fps":{"type":"integer"},"resolution":{"type":"string"},"file_size_bytes":{"type":"integer"},"duration_seconds":{"type":"number"},"deleted_after":{"type":"string","format":"date-time","description":"MOV files only."}}},"error":{"$ref":"#/components/schemas/ErrorBody"},"metadata":{"type":"object"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"}}},"Account":{"type":"object","properties":{"email":{"type":"string"},"plan":{"type":"string"},"api_access":{"type":"boolean"},"credits_remaining":{"type":["number","null"]},"generations_running":{"type":"integer"},"max_generations_running":{"type":"integer"},"limits":{"type":"object"}}},"ErrorBody":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"Error":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/ErrorBody"}}}}}}