{"openapi":"3.1.0","info":{"title":"PIXL Studio Engine API","version":"0.4.2","description":"The engine API used by the BASE44 shell. Every call needs Authorization: Bearer <JWT from studioToken>, except /healthz and this spec. Errors are { error: { code, message } }. The full integration guide covers webhooks, events and credits."},"servers":[{"url":"https://studio.pixl.co.il"}],"security":[{"studioToken":[]}],"components":{"securitySchemes":{"studioToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT (HS256, iss pixl-base44, claims sub pid role iat exp, 15 minutes)"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}},"Order":{"type":"object","description":"Brief section 8. Unknown fields are kept and passed to the agent.","properties":{"type":{"type":"string","example":"motion-ad"},"durationSec":{"type":"number","minimum":5,"maximum":180},"destinations":{"type":"array","items":{"type":"string"}},"formats":{"type":"array","items":{"enum":["9:16","4:5","1:1","16:9"]}},"quality":{"enum":["720p","1080p","4k"]},"presenter":{"type":"object","properties":{"kind":{"enum":["none","self","ai-character","footage"]},"characterId":{"type":["string","null"]},"avatarProfileId":{"type":["string","null"]}}},"voice":{"type":"object","properties":{"kind":{"enum":["character","catalog","cloned","upload","none"]},"voiceProfileId":{"type":["string","null"]},"providerVoiceId":{"type":["string","null"],"description":"voiceId from GET /v1/voices"},"speed":{"type":"number","minimum":0.7,"maximum":1.3}}},"style":{"type":"string"},"captions":{"type":"object","properties":{"on":{"type":"boolean"},"style":{"enum":["pill","bare","pop","highlight","stack","word","sticker","rise","type"]},"fontFamilyId":{"type":["string","null"]},"weight":{"type":"number"},"position":{"type":"string"},"size":{"type":"string"}}},"music":{"type":"object","properties":{"on":{"type":"boolean"},"mood":{"type":"string"}}},"language":{"type":"string"},"content":{"type":"object","properties":{"url":{"type":"string"},"sells":{"type":"string"},"offer":{"type":"string"},"audience":{"type":"string"},"pain":{"type":"string"},"cta":{"type":"string"},"proofs":{"type":"array"},"forbidden":{"type":"array"},"script":{}}},"runMode":{"enum":["every-gate","key-gates","fast"]},"brandId":{"type":["string","null"]}}},"Costs":{"type":"object","properties":{"estimate":{"type":"integer"},"reserved":{"type":"integer"},"charged":{"type":"integer"}}},"Review":{"type":"object","properties":{"reviewId":{"type":"string"},"gate":{"enum":["G0","G1","G2","G3","G4"]},"version":{"type":"integer"},"summary":{"type":"string"},"package":{"type":"object"},"suggestions":{"type":"array","items":{"type":"string"}},"missing":{"type":"array","items":{"type":"string"}},"cost":{"type":["object","null"]}}},"Project":{"type":"object","properties":{"engineProjectId":{"type":"string"},"projectId":{"type":"string"},"stage":{"type":"string"},"status":{"enum":["active","waiting_user","failed","cancelled","delivered"]},"failReason":{"type":["string","null"]},"planSummary":{"type":"object"},"assets":{"type":"array","items":{"type":"object"}},"costs":{"$ref":"#/components/schemas/Costs"},"pendingReview":{"oneOf":[{"$ref":"#/components/schemas/Review"},{"type":"null"}]},"finalUrl":{"type":["string","null"]},"thumbUrl":{"type":["string","null"]}}},"Voice":{"type":"object","properties":{"voiceId":{"type":"string"},"name":{"type":"string"},"nameHe":{"type":"string"},"gender":{"enum":["male","female"]},"pitch":{"type":"string"},"persona":{"type":"string"},"description":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"sampleUrl":{"type":["string","null"]},"rank":{"type":"integer"},"isDefault":{"type":"boolean"}}}}},"paths":{"/healthz":{"get":{"security":[],"summary":"Health of the engine and its services","responses":{"200":{"description":"{ ok, version, checks }"}}}},"/v1/openapi.json":{"get":{"security":[],"summary":"This spec","responses":{"200":{"description":"OpenAPI document"}}}},"/v1/handshake":{"get":{"summary":"Connection test: what the engine sees in your token, origin and webhook settings","responses":{"200":{"description":"{ ok, engine, token, origin, webhook, capabilities }"}}}},"/v1/handshake/events":{"get":{"summary":"Connection test: a 10 second event stream (one message, five pings)","responses":{"200":{"description":"text/event-stream"}}}},"/v1/handshake/webhook":{"post":{"summary":"Connection test (admin): the engine signs and sends engine.ping to studioWebhook","responses":{"200":{"description":"{ sent, eventId, status, ms, signatureAccepted, answer }"}}}},"/v1/capabilities":{"get":{"summary":"Which media capabilities are connected","responses":{"200":{"description":"{ capabilities: { voice, music, image, video, avatar, lipsync, stock, sfx, upscale, fonts } }"}}}},"/v1/estimate":{"post":{"summary":"Credit estimate for an order","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"order":{"$ref":"#/components/schemas/Order"}}}}}},"responses":{"200":{"description":"{ credits, breakdown: [{ item, credits }], etaSec }"},"400":{"description":"bad_order"}}}},"/v1/preview/still":{"post":{"summary":"One sample frame in the order's caption style and the brand colors (rate limited, no credits)","responses":{"200":{"description":"{ imageUrl, ttlSec }"}}}},"/v1/voices":{"get":{"summary":"The Hebrew voice catalog","parameters":[{"name":"gender","in":"query","schema":{"enum":["male","female"]}},{"name":"q","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"{ voices: Voice[], defaultVoiceId, total, connected }"}}}},"/v1/voices/preview":{"post":{"summary":"Say a short text (120 characters) in a voice","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"voiceId":{"type":"string"},"text":{"type":"string","maxLength":120}}}}}},"responses":{"200":{"description":"{ audioUrl, voiceId }"}}}},"/v1/uploads/sign":{"post":{"summary":"A URL the browser PUTs a file to, straight to storage","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"contentType":{"type":"string"},"sizeBytes":{"type":"integer"},"purpose":{"type":"string"}}}}}},"responses":{"200":{"description":"{ uploadUrl, headers, fileUrl, expiresAt }"}}}},"/v1/fonts":{"get":{"summary":"System fonts and the brand's checked fonts","parameters":[{"name":"brandId","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"{ families }"}}},"post":{"summary":"Upload and check a font file (multipart: file, brandId, family)","requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"},"brandId":{"type":"string"},"family":{"type":"string"}}}}}},"responses":{"200":{"description":"{ fontId, family, weight, style, verdict, hebrewCoverage, weights, embedAllowed, fileUrl, notes, report }"}}}},"/v1/characters":{"get":{"summary":"AI characters of the user and the system","parameters":[{"name":"brandId","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"{ characters }"}}},"post":{"summary":"{ description, brandId } gives four proposals; { pick, name } gives the identity sheet","responses":{"200":{"description":"{ characterId, proposals } or the character"}}}},"/v1/brands/extract":{"post":{"summary":"Name, palette, font and logo from a website","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"}}}}}},"responses":{"200":{"description":"{ name, palette, font, logoUrl, radius, confidence, sourceUrl, candidates }"}}}},"/v1/projects":{"post":{"summary":"Open a project (safe to retry with the same projectId)","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["projectId","order"],"properties":{"projectId":{"type":"string"},"mode":{"enum":["input","director"]},"order":{"$ref":"#/components/schemas/Order"},"brandKit":{"type":"object"},"attachments":{"type":"array"}}}}}},"responses":{"201":{"description":"{ engineProjectId, stage }"}}}},"/v1/projects/{id}":{"get":{"summary":"Current state of a project","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}},"description":"The project"}}}},"/v1/projects/{id}/messages":{"post":{"summary":"A customer message (chat, or an answer to a question)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"{ accepted: true }"}}}},"/v1/projects/{id}/events":{"get":{"summary":"Server sent events with Last-Event-ID replay and a ping every 15 seconds","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Last-Event-ID","in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":"text/event-stream"}}}},"/v1/projects/{id}/reviews/{reviewId}":{"post":{"summary":"The customer's decision on a gate","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"reviewId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"decision":{"enum":["approve","changes","reject"]},"notes":{"type":"string"},"edits":{"type":"array"},"commentIds":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"{ stage }"},"402":{"description":"insufficient_credits (G2): { error: { code, message, balance, needed } }"},"409":{"description":"already_decided or invalid_transition"}}}},"/v1/projects/{id}/comments":{"post":{"summary":"A timeline comment on a draft","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"{ commentId }"}}}},"/v1/projects/{id}/approval-links":{"post":{"summary":"A link for a client to view or approve a gate","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"{ token, expiresAt }"}}}},"/v1/projects/{id}/cancel":{"post":{"summary":"Stop the project and release the credits","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"{ ok: true }"}}}},"/v1/projects/{id}/retry":{"post":{"summary":"Continue a failed project from its stage","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"{ ok: true }"}}}}}}