{"openapi":"3.1.0","info":{"title":"Havincy API","version":"1.0.0","description":"Generate images, videos, voice-overs, music, 3D and Encore effect videos with Havincy, browse your library and brand kits, and publish to social networks. Authenticate with an API key (Authorization: Bearer hv_live_...)."},"servers":[{"url":"https://havincy.com/api/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key (hv_live_...) or OAuth access token."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}}}}},"paths":{"/account":{"get":{"operationId":"getAccount","summary":"Get Havincy account","description":"Returns the connected Havincy workspace: name, credit balance, subscription plan, rate limit and granted scopes. Call it to check credits before generating.\n\nRequired scope: `read`.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/models":{"get":{"operationId":"listModels","summary":"List generation models","description":"Lists the AI models available for generation, grouped by modality (image, video, audio, 3d). Each model gives its credit cost per output, whether it needs a reference image, and the valid options (aspect ratios, durations, resolutions, voices). Use the returned id as model_id.\n\nRequired scope: `read`.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"modality","in":"query","required":false,"schema":{"type":"string","enum":["image","video","audio","3d"]},"description":"Only this modality (default: all)."},{"name":"track","in":"query","required":false,"schema":{"type":"string","enum":["voice","music"]},"description":"Audio only: voice (text to speech) or music."}]}},"/generations":{"post":{"operationId":"generate","summary":"Generate media","description":"Generates images, videos, voice-overs, music or 3D models with Havincy and charges credits. Pick a model_id from list_models. Generation is asynchronous: the response contains the created assets with status queued/processing; set wait_seconds (max 55) to wait for the result, or poll get_generation. Reference images (image-to-image, image-to-video, image-to-3D) come from reference_asset_ids (library) or reference_image_urls (public https URLs or data URIs).\n\nRequired scope: `generate`.","responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"modality":{"type":"string","enum":["image","video","audio","3d"],"description":"image, video, audio or 3d."},"track":{"type":"string","enum":["voice","music"],"description":"Audio only: voice (default) or music."},"model_id":{"type":"string","description":"Model id from list_models."},"prompt":{"type":"string","description":"What to create. For voice: the exact text to speak.","maxLength":5000},"count":{"type":"integer","minimum":1,"maximum":4,"description":"Number of outputs (images only, up to 4)."},"aspect_ratio":{"type":"string","description":"Image or video aspect ratio, e.g. 1:1, 9:16, 16:9."},"resolution":{"type":"string","description":"Image resolution (e.g. 1k, 2k) or video resolution (e.g. 720p, 1080p)."},"duration":{"type":"integer","description":"Video duration in seconds (see model options)."},"generate_audio":{"type":"boolean","description":"Video: generate native audio when the model supports it."},"voice":{"type":"string","description":"Voice id for text to speech (see model options)."},"language":{"type":"string","description":"Voice language code, e.g. fr, en."},"reference_asset_ids":{"type":"array","items":{"type":"integer"},"maxItems":4,"description":"Library image asset ids used as references."},"reference_image_urls":{"type":"array","items":{"type":"string"},"maxItems":4,"description":"Public image URLs (https) or data URIs used as references."},"wait_seconds":{"type":"integer","minimum":0,"maximum":55,"description":"Wait up to N seconds for completion (default 0)."}},"required":["modality","model_id","prompt"]}}}}}},"/generations/{id}":{"get":{"operationId":"getGeneration","summary":"Get generation status","description":"Returns the status and result URLs of one or more assets created by generate, create_encore or upload_image. Status is queued, processing, completed or failed. Set wait_seconds to wait for completion.\n\nRequired scope: `read`.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"wait_seconds","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":55},"description":"Wait up to N seconds for completion (default 0)."}]}},"/assets":{"get":{"operationId":"listAssets","summary":"List library assets","description":"Lists media in the Havincy library (newest first): images, videos, voice, music, 3D and uploads. Filter by kind or status, search by prompt/title, paginate with starting_after.\n\nRequired scope: `read`.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"kind","in":"query","required":false,"schema":{"type":"string","enum":["image","video","voice","music","audio","model3d","upload"]}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["queued","processing","completed","failed"]}},{"name":"query","in":"query","required":false,"schema":{"type":"string"},"description":"Search in title and prompt."},{"name":"project_id","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50},"description":"Default 20."},{"name":"starting_after","in":"query","required":false,"schema":{"type":"integer"},"description":"Cursor: last asset id of the previous page."}]}},"/assets/{id}":{"get":{"operationId":"getAsset","summary":"Get generation status","description":"Returns the status and result URLs of one or more assets created by generate, create_encore or upload_image. Status is queued, processing, completed or failed. Set wait_seconds to wait for completion.\n\nRequired scope: `read`.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"wait_seconds","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":55},"description":"Wait up to N seconds for completion (default 0)."}]}},"/uploads":{"post":{"operationId":"uploadImage","summary":"Upload an image","description":"Imports an image into the Havincy library (free, no credits) from a public https URL or a data URI (JPEG, PNG or WEBP, max 10 MB). Returns an asset id usable in reference_asset_ids or create_encore.\n\nRequired scope: `generate`.","responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"image_url":{"type":"string","description":"Public https URL or data:image/...;base64,... URI."},"title":{"type":"string","maxLength":160}},"required":[]}},"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"},"title":{"type":"string"}},"required":["file"]}}}}}},"/encore/effects":{"get":{"operationId":"listEncoreEffects","summary":"List Encore effects","description":"Lists Encore effects: one-click viral video effects that turn a single photo into a 5-8 s vertical (9:16) video (e.g. melt, inflate, giant in the city). Returns each effect slug, name, tagline and credit cost.\n\nRequired scope: `read`.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/encore/creations":{"post":{"operationId":"createEncore","summary":"Create an Encore video","description":"Turns one photo into a viral vertical video with an Encore effect (see list_encore_effects) and charges the effect's credits. Provide exactly one subject: image_url (public https URL or data URI), asset_id (library image) or character_id (see list_characters). The video renders asynchronously: poll get_encore_creation (or set wait_seconds).\n\nRequired scope: `generate`.","responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"effect":{"type":"string","description":"Effect slug from list_encore_effects."},"image_url":{"type":"string","description":"Photo as public https URL or data URI (JPEG, PNG, WEBP; min 480 px)."},"asset_id":{"type":"integer","description":"Library image asset id."},"character_id":{"type":"integer","description":"Character id from list_characters."},"wait_seconds":{"type":"integer","minimum":0,"maximum":55,"description":"Wait up to N seconds for completion (default 0)."}},"required":["effect"]}}}}}},"/encore/creations/{id}":{"get":{"operationId":"getEncoreCreation","summary":"Get Encore creation","description":"Returns an Encore creation: status (queued, processing, completed, failed), video URL and public share link when ready.\n\nRequired scope: `read`.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"wait_seconds","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":55},"description":"Wait up to N seconds for completion (default 0)."}]}},"/characters":{"get":{"operationId":"listCharacters","summary":"List characters","description":"Lists the ready Havincy characters of the workspace (reusable visual identities). A character id can replace the photo in create_encore.\n\nRequired scope: `read`.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/brand_kits":{"get":{"operationId":"listBrandKits","summary":"List brand kits","description":"Lists the workspace brand kits (niche, tone, target audience, master instructions, colors, fonts). Use them to write on-brand prompts before calling generate.\n\nRequired scope: `read`.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50}},{"name":"starting_after","in":"query","required":false,"schema":{"type":"integer"}}]}},"/projects":{"get":{"operationId":"listProjects","summary":"List projects","description":"Lists the workspace projects (newest first) with their status and link. Use project_id in list_assets to see a project's media.\n\nRequired scope: `read`.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50}},{"name":"starting_after","in":"query","required":false,"schema":{"type":"integer"}}]}},"/social/accounts":{"get":{"operationId":"listSocialAccounts","summary":"List connected social accounts","description":"Lists the social accounts connected in Havincy Diffusion (TikTok, Instagram, YouTube…) and whether the plan allows publishing. Accounts are connected from the Havincy app, not through the API.\n\nRequired scope: `read`.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/social/publications":{"get":{"operationId":"listPublications","summary":"List publications","description":"Lists social publications (newest first), optionally filtered by status.\n\nRequired scope: `read`.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["draft","ready","scheduled","publishing","published","partially_published","failed","cancelled"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50}},{"name":"starting_after","in":"query","required":false,"schema":{"type":"integer"}}]},"post":{"operationId":"publishToSocial","summary":"Publish to social networks","description":"Publishes ready media to the connected social accounts (see list_social_accounts), now or at scheduled_at (ISO 8601, future). One video, or up to 10 images as a carousel. This posts publicly on the user's networks: only call it when the user explicitly asked to publish.\n\nRequired scope: `publish`.","responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"asset_ids":{"type":"array","items":{"type":"integer"},"minItems":1,"maxItems":10,"description":"Ready image/video asset ids."},"caption":{"type":"string","maxLength":2200,"description":"Post caption (hashtags included)."},"social_account_ids":{"type":"array","items":{"type":"integer"},"description":"Target accounts (from list_social_accounts)."},"platforms":{"type":"array","items":{"type":"string"},"description":"Or target platforms (first connected account of each)."},"scheduled_at":{"type":"string","description":"ISO 8601 date-time in the future. Omit to publish now."},"options":{"type":"object","additionalProperties":false,"properties":{"youtube_format":{"type":"string","enum":["short","video"]},"title":{"type":"string","maxLength":100,"description":"Title (YouTube)."}}}},"required":["asset_ids","caption"]}}}}}},"/social/publications/{id}":{"get":{"operationId":"getPublication","summary":"Get publication","description":"Returns a social publication with its per-platform delivery status and post URLs.\n\nRequired scope: `read`.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}]}}}}