{"openapi":"3.1.0","info":{"title":"QOYO Studio API","version":"1.0.0","description":"Public API for AI agents and MCP integrations. Billing uses the same QOYO account balance as the web studio. Referral rewards do not apply to API usage charges."},"servers":[{"url":"https://qoyo.ru/api/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Personal API key from QOYO account cabinet (prefix qoyo_sk_)"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"Me":{"type":"object","properties":{"userId":{"type":"string"},"balanceCredits":{"type":"integer"},"apiDiscountPercent":{"type":"integer"},"keyPrefix":{"type":"string","nullable":true},"topUpUrl":{"type":"string"},"docsUrl":{"type":"string"}}},"GenerateRequest":{"type":"object","required":["model","input"],"properties":{"model":{"type":"string","description":"Catalog model id"},"input":{"type":"object","additionalProperties":true},"idempotencyKey":{"type":"string","minLength":8,"maxLength":200}}},"Task":{"type":"object","properties":{"id":{"type":"string"},"model":{"type":"string"},"state":{"type":"string","enum":["waiting","queuing","generating","success","fail"]},"resultUrls":{"type":"array","items":{"type":"string"}},"creditsCharged":{"type":"integer"}}}}},"paths":{"/me":{"get":{"summary":"Account balance and API discount","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}},"401":{"description":"Unauthorized"}}}},"/catalog":{"get":{"summary":"List studio models","responses":{"200":{"description":"Model list"}}}},"/catalog/{modelId}":{"get":{"summary":"Model schema (fields and defaults)","parameters":[{"name":"modelId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Model detail"},"404":{"description":"Not found"}}}},"/price":{"post":{"summary":"Estimate credits for a generation","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["model","input"],"properties":{"model":{"type":"string"},"input":{"type":"object"}}}}}},"responses":{"200":{"description":"credits, totalRub, billingInput (normalized input used for billing), optional klingAvatarBilling"}}}},"/generate":{"post":{"summary":"Start a studio generation","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateRequest"}}}},"responses":{"200":{"description":"Task created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}},"402":{"description":"Insufficient credits"}}}},"/tasks":{"get":{"summary":"List recent tasks","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":30}}],"responses":{"200":{"description":"Task list"}}}},"/tasks/{id}":{"get":{"summary":"Get task status (optional sync with provider)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"sync","in":"query","schema":{"type":"string","enum":["1"]}}],"responses":{"200":{"description":"Task"},"404":{"description":"Not found"}}}},"/uploads":{"post":{"summary":"Upload image/video/audio; returns URL for model input","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Public URL on QOYO"}}}},"/style/price":{"post":{"summary":"Estimate credits for AI stylist session (3 looks)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"genModel":{"type":"string","enum":["nano-banana-pro","gpt-image-2-image-to-image"]},"resolution":{"type":"string","enum":["1K","2K","4K"]}}}}}},"responses":{"200":{"description":"credits estimate"}}}},"/style/outfits":{"post":{"summary":"Start AI outfit session with try-on (nano-banana-pro / GPT Image 2)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["personImageUrl","gender","styleKey","formatKey","maxBudgetRub"],"properties":{"personImageUrl":{"type":"string"},"gender":{"type":"string","enum":["male","female","unisex"]},"styleKey":{"type":"string"},"formatKey":{"type":"string","enum":["full","upper","evening"]},"maxBudgetRub":{"type":"number"},"genModel":{"type":"string"},"resolution":{"type":"string"},"occasion":{"type":"string"}}}}}},"responses":{"200":{"description":"Session created"},"402":{"description":"Insufficient credits"}}}},"/style/outfits/{id}":{"get":{"summary":"Poll outfit session status and results","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Session with looks"},"404":{"description":"Not found"}}}},"/style/catalog":{"get":{"summary":"Search active style catalog products","parameters":[{"name":"slot","in":"query","schema":{"type":"string"}},{"name":"gender","in":"query","schema":{"type":"string"}},{"name":"q","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"offset","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Product list"}}}},"/style/tryon":{"post":{"summary":"Start product try-on session with fixed SKUs (store owner API key)","responses":{"200":{"description":"Session created"},"402":{"description":"Insufficient credits"}}}},"/style/tryon/{id}":{"get":{"summary":"Poll product try-on session","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Session"},"404":{"description":"Not found"}}}},"/merchant/catalog/sync":{"put":{"summary":"Batch upsert catalog (merchant API key qoyo_msk_)","responses":{"200":{"description":"Sync result"}}}},"/merchant/catalog/health":{"get":{"summary":"Catalog health report","responses":{"200":{"description":"Health"}}}},"/merchant/tryon":{"post":{"summary":"Start try-on (merchant API key)","responses":{"200":{"description":"Session"}}}},"/merchant/tryon/{id}":{"get":{"summary":"Poll try-on session","responses":{"200":{"description":"Session"}}}},"/merchant/webhooks":{"post":{"summary":"Configure merchant webhook URL","responses":{"200":{"description":"Configured"}}}}}}