{"openapi":"3.1.0","info":{"title":"Studio Pass API","version":"1.0.0","description":"Images, video, and voice on one Studio Pass membership."},"servers":[{"url":"https://getstudiopass.com"}],"security":[{"bearer":[]}],"paths":{"/v1/models":{"get":{"summary":"List the models this account has switched on, with prices, lengths, and this account's defaults","operationId":"listModels","responses":{"200":{"description":"Live models","content":{"application/json":{"schema":{"type":"object","properties":{"models":{"type":"array","items":{"$ref":"#/components/schemas/Model"}}}}}}},"401":{"description":"Missing or invalid key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/generations":{"post":{"summary":"Create an image, video, or voice generation","operationId":"createGeneration","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":false,"required":["modality","prompt"],"properties":{"modality":{"const":"image"},"model":{"enum":["gpt-image-2.5-flare","gpt-image-2.5-sunburst","nano-banana-2","grok-imagine-image-2.0"]},"prompt":{"type":"string","maxLength":4000},"orientation":{"enum":["square","portrait","landscape"],"description":"Where the model offers it; see the model's orientations."},"reference_image_id":{"type":"string","description":"A reference image from POST /v1/uploads. The image model edits it; the video clip starts from it."},"reference_image_url":{"type":"string","format":"uri","description":"A public https image URL to use as the reference. Send this or reference_image_id, not both."},"confirm_credits":{"type":"integer","description":"Only when the account's confirmation limit applies: the exact credit cost the member agreed to, as given in the confirmation_required error."}}},{"type":"object","additionalProperties":false,"required":["modality","prompt"],"properties":{"modality":{"const":"video"},"model":{"enum":["gemini-omni-flash-1.1","kling-3.0","veo-3.1","minimax-h3","wan-3.0"]},"prompt":{"type":"string","maxLength":4000},"duration_seconds":{"type":"integer"},"orientation":{"enum":["landscape","portrait"],"description":"16:9 or 9:16, where the model offers it. Omit for landscape."},"reference_image_id":{"type":"string","description":"A reference image from POST /v1/uploads. The image model edits it; the video clip starts from it."},"reference_image_url":{"type":"string","format":"uri","description":"A public https image URL to use as the reference. Send this or reference_image_id, not both."},"confirm_credits":{"type":"integer","description":"Only when the account's confirmation limit applies: the exact credit cost the member agreed to, as given in the confirmation_required error."}}},{"type":"object","additionalProperties":false,"required":["modality","text"],"properties":{"modality":{"const":"voice"},"model":{"enum":["elevenlabs-v3"]},"text":{"type":"string","maxLength":5000},"voice":{"type":"string","description":"A voice from the model's voices. Omit for the first."},"delivery":{"enum":["expressive","natural","steady"]},"confirm_credits":{"type":"integer","description":"Only when the account's confirmation limit applies: the exact credit cost the member agreed to, as given in the confirmation_required error."}}}]}}}},"responses":{"200":{"description":"Finished within the wait; read status for succeeded or failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Generation"}}}},"202":{"description":"Accepted and still running","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Generation"}}}},"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":"subscription_inactive or insufficient_credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"account_suspended or model_disabled (switched off in the account's model settings)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"428":{"description":"confirmation_required: the cost is above the account's confirmation limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited or new_account_limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"busy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/uploads":{"post":{"summary":"Add a reference image for generations to follow","description":"Send the image as the raw body (image/jpeg, image/png, image/webp, …) or as a multipart form field named file, at most 4 MB. It is kept for 7 days, or with ?name= it is saved to the member's library until deleted.","operationId":"createUpload","parameters":[{"name":"name","in":"query","required":false,"schema":{"type":"string","maxLength":80},"description":"Save to the library under this name."}],"requestBody":{"required":true,"content":{"image/*":{"schema":{"type":"string","format":"binary"}},"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}},"required":["file"]}}}},"responses":{"201":{"description":"The reference image","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferenceImage"}}}},"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":"subscription_inactive","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/brief":{"get":{"summary":"The questions worth asking before a generation, with this account's options and prices","description":"Returns format, length, voice, reference, and style questions for the modality, each with the parameter it sets, options, and a suggested answer, plus prompt tips. ask_first says whether the member wants to be asked.","operationId":"getBrief","parameters":[{"name":"modality","in":"query","required":true,"schema":{"enum":["image","video","voice"]}}],"responses":{"200":{"description":"The brief","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"invalid_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/references":{"get":{"summary":"List the member's saved reference images","operationId":"listReferences","responses":{"200":{"description":"Saved images","content":{"application/json":{"schema":{"type":"object","properties":{"images":{"type":"array","items":{"$ref":"#/components/schemas/ReferenceImage"}}}}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/generations/{id}":{"get":{"summary":"Read a generation","operationId":"getGeneration","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The generation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Generation"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"A Studio Pass key (sp_live_…) or an OAuth access token."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"enum":["unauthorized","subscription_inactive","insufficient_credits","account_suspended","rate_limited","new_account_limit","busy","invalid_request","model_disabled","confirmation_required","not_found"]},"message":{"type":"string"}},"required":["code","message"]}}},"Model":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"modality":{"enum":["image","video","voice"]},"tier":{"enum":["budget","standard","premium"]},"best_for":{"type":"string"},"typical_cost":{"type":"string"},"credits_per_unit":{"type":"integer"},"billing_unit":{"enum":["image","second","1000_characters"]},"allowed_duration_seconds":{"type":["array","null"],"items":{"type":"integer"}},"default_duration_seconds":{"type":["integer","null"]},"prompt_limit":{"type":"integer"},"orientations":{"type":["array","null"],"items":{"enum":["landscape","portrait","square"]}},"sound":{"type":"boolean","description":"Video models: whether the clip has sound"},"voices":{"type":"array","items":{"type":"string"},"description":"Voice models: the voices a call may choose"},"orientation_with_reference_image":{"type":["string","null"]},"accepts_reference_image":{"type":"boolean"},"credits_per_unit_with_reference_image":{"type":["integer","null"]},"is_default":{"type":"boolean"},"requires_model_id":{"type":"boolean"}}},"ReferenceImage":{"type":"object","properties":{"reference_image_id":{"type":"string"},"status":{"enum":["pending","ready"]},"name":{"type":"string","description":"Present for an image saved to the library"},"saved_in_library":{"type":"boolean"},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"expires_at":{"type":["string","null"],"format":"date-time","description":"Null for an image saved to the library"}}},"Generation":{"type":"object","properties":{"id":{"type":"string"},"status":{"enum":["running","succeeded","failed"]},"modality":{"enum":["image","video","voice"]},"model":{"type":"string"},"credits_reserved":{"type":"integer"},"credits_charged":{"type":"integer"},"duration_seconds":{"type":["integer","null"]},"reference_image_id":{"type":["string","null"]},"file_url":{"type":["string","null"],"description":"Stable link, valid for 30 days"},"content_type":{"type":["string","null"]},"error":{"type":["object","null"],"properties":{"code":{"enum":["generation_failed","content_refused"]},"message":{"type":"string"}}},"created_at":{"type":"string","format":"date-time"},"balance":{"type":"object","properties":{"included":{"type":"integer"},"topup":{"type":"integer"},"total":{"type":"integer"}}}}}}}}