{"openapi":"3.1.0","info":{"title":"Phantasia API","version":"1.0.0","description":"Make pictures, songs, voices and short clips with open models. Creations run in the background: start one, then check it or get a webhook. Docs: https://phantasia.pics/docs"},"servers":[{"url":"https://phantasia.pics/api/v1"}],"security":[{"key":[]}],"components":{"securitySchemes":{"key":{"type":"http","scheme":"bearer","description":"An API key from https://phantasia.pics/developers (phk_…)"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"Options":{"type":"object","description":"All optional. Which ones apply depends on kind.","properties":{"aspect":{"type":"string","enum":["square","portrait","landscape"],"description":"image, video"},"seconds":{"type":"integer","description":"music 10–60 (default 30); sound 5, 10, 20, 30"},"lyrics":{"type":"string","maxLength":1000,"description":"music"},"instrumental":{"type":"boolean","description":"music"},"voice":{"type":"string","enum":["af_heart","af_bella","am_michael","am_fenrir","bf_emma","bm_george","tk_mms"],"description":"voice"},"speed":{"type":"number","minimum":0.8,"maximum":1.3,"description":"voice"},"length":{"type":"string","enum":["short","long"],"description":"video: 2 s or 4 s"},"quality":{"type":"string","enum":["hd"],"description":"video: best-quality 5 s clip (when switched on)"},"sound":{"type":"string","enum":["none","music","narration"],"description":"video soundtrack"},"sound_prompt":{"type":"string","maxLength":200,"description":"video with sound \"music\": the style"},"narration":{"type":"string","maxLength":200,"description":"video with sound \"narration\": the words"}}},"Creation":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["image","music","voice","video","sound"]},"status":{"type":"string","enum":["queued","running","done","failed","blocked"]},"prompt":{"type":"string"},"url":{"type":["string","null"],"description":"The file, when done"},"error":{"type":["string","null"]},"shared":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"finished_at":{"type":["string","null"],"format":"date-time"}}},"WebhookEvent":{"type":"object","description":"POSTed to your webhook, signed: webhook-id, webhook-timestamp, webhook-signature (v1,base64 HMAC-SHA256 of id.timestamp.body with your whsec_ secret).","properties":{"type":{"type":"string","enum":["creation.done","creation.failed"]},"creation":{"$ref":"#/components/schemas/Creation"}}}}},"paths":{"/creations":{"post":{"operationId":"createCreation","summary":"Start a creation","parameters":[{"name":"X-Webhook-URL","in":"header","required":false,"schema":{"type":"string","format":"uri"},"description":"Same as body.webhook"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["kind","prompt"],"properties":{"kind":{"type":"string","enum":["image","music","voice","video","sound"]},"prompt":{"type":"string","minLength":3,"maxLength":500},"options":{"$ref":"#/components/schemas/Options"},"webhook":{"type":"string","format":"uri","description":"https address that gets a signed POST when it finishes"}}}}}},"responses":{"202":{"description":"Started","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string"},"status":{"type":"string","const":"queued"},"wait":{"type":"string"}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listCreations","summary":"Your recent creations, newest first","parameters":[{"name":"kind","in":"query","schema":{"type":"string","enum":["image","music","voice","video","sound"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"creations":{"type":"array","items":{"$ref":"#/components/schemas/Creation"}}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/creations/{id}":{"get":{"operationId":"getCreation","summary":"One creation: status, and its file url when done","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Creation"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/creations/{id}/share":{"post":{"operationId":"shareCreation","summary":"Put it in the public gallery, or take it out with {\"shared\": false}","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"shared":{"type":"boolean","default":true}}}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/usage":{"get":{"operationId":"getUsage","summary":"Today's allowance per kind ({kind}_used, {kind}_limit)","responses":{"200":{"description":"OK"},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/models":{"get":{"operationId":"listModels","summary":"The open models behind Phantasia","security":[],"responses":{"200":{"description":"OK"}}}},"/webhooks/secret":{"get":{"operationId":"getWebhookSecret","summary":"Your webhook signing secret (whsec_…)","responses":{"200":{"description":"OK"},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}