{"openapi":"3.1.0","info":{"title":"GenPixy API","version":"1","description":"Make narrated explainer videos from a topic or a script. Docs: https://www.genpixy.com/api/docs"},"servers":[{"url":"https://www.genpixy.com/api/v1"}],"security":[{"bearer":[]}],"paths":{"/videos":{"post":{"operationId":"createVideo","summary":"Create a video","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVideoRequest"}}}},"responses":{"200":{"description":"Same Idempotency-Key and request: the first video","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Video"}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Video"}}}},"400":{"description":"INVALID_REQUEST","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHORIZED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"INSUFFICIENT_BALANCE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"ACCOUNT_SUSPENDED or ACCOUNT_NOT_READY","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"IDEMPOTENCY_KEY_REUSED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"PROMPT_REFUSED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED or TOO_MANY_ACTIVE_VIDEOS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"INTERNAL_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"TRY_AGAIN or SERVICE_UNAVAILABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listVideos","summary":"List videos","parameters":[{"name":"after","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"One page, newest first","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/VideoSummary"}},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["object","data","next_cursor"]}}}},"400":{"description":"INVALID_REQUEST","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHORIZED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"ACCOUNT_SUSPENDED or ACCOUNT_NOT_READY","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED or TOO_MANY_ACTIVE_VIDEOS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"INTERNAL_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/videos/{id}":{"get":{"operationId":"getVideo","summary":"Check a video","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The video","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Video"}}}},"400":{"description":"INVALID_REQUEST","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHORIZED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"ACCOUNT_SUSPENDED or ACCOUNT_NOT_READY","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED or TOO_MANY_ACTIVE_VIDEOS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"INTERNAL_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/videos/{id}/content":{"get":{"operationId":"downloadVideoFile","summary":"Download a file","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"variant","in":"query","required":false,"schema":{"type":"string","enum":["video","thumbnail","subtitles"],"default":"video"}}],"responses":{"200":{"description":"The file (video/mp4, image/png, or application/x-subrip)"},"206":{"description":"A byte range of the video"},"400":{"description":"INVALID_REQUEST","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHORIZED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"ACCOUNT_SUSPENDED or ACCOUNT_NOT_READY","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"VIDEO_NOT_READY","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"FILE_EXPIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED or TOO_MANY_ACTIVE_VIDEOS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"INTERNAL_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/account":{"get":{"operationId":"getAccount","summary":"Balance and videos in progress","responses":{"200":{"description":"The account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"400":{"description":"INVALID_REQUEST","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHORIZED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"ACCOUNT_SUSPENDED or ACCOUNT_NOT_READY","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED or TOO_MANY_ACTIVE_VIDEOS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"INTERNAL_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/options":{"get":{"operationId":"getOptions","summary":"Options, defaults, and costs","responses":{"200":{"description":"The options","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Options"}}}},"400":{"description":"INVALID_REQUEST","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHORIZED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"ACCOUNT_SUSPENDED or ACCOUNT_NOT_READY","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED or TOO_MANY_ACTIVE_VIDEOS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"INTERNAL_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"gpx_… API key"}},"schemas":{"CreateVideoRequest":{"type":"object","properties":{"prompt":{"type":"string","minLength":3,"maxLength":5000,"description":"A topic, notes, or a full script. Line breaks and Markdown lists are fine. Write it in the language the narration should use."},"seconds":{"default":60,"type":"integer","enum":[30,60,90,120,180,300,480,600],"description":"Target length."},"orientation":{"default":"landscape","type":"string","enum":["landscape","portrait"]},"resolution":{"default":"720p","type":"string","enum":["720p","1080p"]},"style":{"default":"whiteboard","type":"string","enum":["whiteboard","animate","flat"],"description":"whiteboard: hand-drawn whiteboard animation. animate: cartoon animation with characters. flat: Color Board (bold colored scenes)."},"language":{"default":"auto","type":"string","enum":["auto","en","id"],"description":"auto: narration follows the prompt language (76 languages)."},"voice":{"default":"male","type":"string","enum":["male","female"]},"subtitles":{"default":true,"type":"boolean"},"music":{"default":true,"type":"boolean"},"big_board":{"default":false,"type":"boolean","description":"All scenes on one board with a zoom-out recap at the end."},"zoom_dive":{"default":false,"type":"boolean","description":"The camera flies into an icon when the next scene looks closer at it."}},"required":["prompt"],"additionalProperties":false},"Amount":{"type":"object","properties":{"units":{"type":"integer"},"display":{"type":"string"}},"required":["units","display"]},"Video":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"video"},"status":{"type":"string","enum":["queued","in_progress","completed","failed","canceled"]},"progress":{"type":"integer"},"queue_position":{"anyOf":[{"type":"integer"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"cost":{"$ref":"#/components/schemas/Amount"},"request":{"type":"object","properties":{"prompt":{"type":"string"},"seconds":{"type":"integer"},"orientation":{"type":"string","enum":["landscape","portrait"]},"resolution":{"type":"string","enum":["720p","1080p"]},"style":{"type":"string","enum":["whiteboard","animate","flat"]},"language":{"type":"string","enum":["auto","en","id"]},"voice":{"type":"string"},"subtitles":{"type":"boolean"},"music":{"type":"boolean"},"big_board":{"type":"boolean"},"zoom_dive":{"type":"boolean"}},"required":["prompt","seconds","orientation","resolution","style","language","voice","subtitles","music","big_board","zoom_dive"]},"result":{"anyOf":[{"type":"object","properties":{"title":{"type":"string"},"duration_seconds":{"type":"number"},"width":{"type":"integer"},"height":{"type":"integer"},"size_bytes":{"type":"integer"},"youtube_title":{"type":"string"},"youtube_description":{"type":"string"},"hashtags":{"type":"array","items":{"type":"string"}},"files":{"type":"object","properties":{"video":{"type":"string"},"thumbnail":{"anyOf":[{"type":"string"},{"type":"null"}]},"subtitles":{"type":"string"}},"required":["video","thumbnail","subtitles"]}},"required":["title","duration_seconds","width","height","size_bytes","youtube_title","youtube_description","hashtags","files"]},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},{"type":"null"}]},"app_url":{"type":"string"}},"required":["id","object","status","progress","queue_position","created_at","started_at","completed_at","expires_at","cost","request","result","error","app_url"]},"VideoSummary":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"video"},"status":{"type":"string","enum":["queued","in_progress","completed","failed","canceled"]},"progress":{"type":"integer"},"title":{"type":"string"},"seconds":{"anyOf":[{"type":"integer"},{"type":"null"}]},"orientation":{"type":"string"},"style":{"type":"string"},"cost":{"$ref":"#/components/schemas/Amount"},"created_at":{"type":"string","format":"date-time"},"app_url":{"type":"string"}},"required":["id","object","status","progress","title","seconds","orientation","style","cost","created_at","app_url"]},"Account":{"type":"object","properties":{"object":{"const":"account"},"email":{"type":"string"},"balance":{"$ref":"#/components/schemas/Amount"},"reserved":{"$ref":"#/components/schemas/Amount"},"active_videos":{"type":"integer"},"max_active_videos":{"type":"integer"},"top_up_url":{"type":"string"}},"required":["object","email","balance","reserved","active_videos","max_active_videos","top_up_url"]},"Options":{"type":"object","description":"Every option, its default, and the cost per length and resolution."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","ACCOUNT_SUSPENDED","ACCOUNT_NOT_READY","INVALID_REQUEST","UNSUPPORTED_MEDIA_TYPE","PAYLOAD_TOO_LARGE","NOT_FOUND","METHOD_NOT_ALLOWED","INSUFFICIENT_BALANCE","IDEMPOTENCY_KEY_REUSED","PROMPT_REFUSED","RATE_LIMITED","TOO_MANY_ACTIVE_VIDEOS","VIDEO_NOT_READY","FILE_EXPIRED","SERVICE_UNAVAILABLE","TRY_AGAIN","INTERNAL_ERROR"]},"message":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message","request_id"]}},"required":["error"]}}}}