{"openapi":"3.1.0","info":{"title":"IBCreator AI Studio & M2M Bot API","version":"1.0.0","description":"Official REST API and Machine-to-Machine (M2M) interface for IBCreator Studio. Enables autonomous AI agents, social bots, and workflows to manage AI Influencer personas, generate identity-consistent 4K photoshoots, and query account credit balances.","contact":{"name":"IBCreator Support","email":"support@ibcreator.app","url":"https://ibcreator.app"}},"servers":[{"url":"https://ibcreator.app","description":"Production Server"},{"url":"http://localhost:3000","description":"Local Development Server"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Provide your API key prefixed with 'ibc_live_' (e.g., 'Bearer ibc_live_...')"},"apiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Provide your API key in the 'x-api-key' header."}},"schemas":{"Persona":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"identity":{"type":"string"},"style_notes":{"type":"string"},"rules":{"type":"string"},"reference_images_count":{"type":"integer"},"created_at":{"type":"integer"}},"required":["id","name","identity"]},"CreatePersonaInput":{"type":"object","properties":{"name":{"type":"string","description":"Name of the AI influencer"},"identity":{"type":"string","description":"Detailed persona identity and bio"},"style_notes":{"type":"string","description":"Wardrobe, camera, and lighting rules"},"rules":{"type":"string","description":"Negative constraints and strict rules"},"refs":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"label":{"type":"string"}}}}},"required":["name","identity"]},"ShootInput":{"type":"object","properties":{"persona_id":{"type":"string","description":"ID of the target persona"},"prompt":{"type":"string","description":"Scene and environment prompt"},"tier":{"type":"string","enum":["basic","pro"],"default":"basic"},"aspect_ratios":{"type":"array","items":{"type":"string"},"default":["1:1"],"description":"Aspect ratios: '1:1', '4:5', '9:16', '16:9'"},"variation_count":{"type":"integer","minimum":1,"maximum":12,"default":1},"webhook_url":{"type":"string","format":"uri","description":"Optional callback URL when shoot completes"}},"required":["prompt"]},"ShootResponse":{"type":"object","properties":{"shoot_id":{"type":"string"},"status":{"type":"string","enum":["pending","running","completed","failed"]},"persona_id":{"type":"string"},"prompt":{"type":"string"},"estimated_credits":{"type":"integer"},"check_url":{"type":"string"}}},"VideoInput":{"type":"object","properties":{"source_path":{"type":"string","description":"Storage path to photo to animate"},"export_id":{"type":"string","description":"Photoshoot export ID to animate"},"persona_id":{"type":"string","description":"Persona ID whose reference photo to animate"},"preset":{"type":"string","enum":["living_portrait","breeze","dolly_in","ambient","dance","ugc_talking","runway_walk","dramatic_turn","fitness_workout","laugh_smile"],"default":"living_portrait","description":"High-motion or micro-motion style preset (e.g. 'dance', 'ugc_talking')"},"camera_motion":{"type":"string","enum":["selfie_handheld","cinematic_orbit","static_tripod","tracking_steadicam","dolly_zoom"],"description":"Camera movement perspective"},"motion_intensity":{"type":"string","enum":["subtle","moderate","energetic"],"description":"Movement tempo and amplitude"},"prompt":{"type":"string","description":"Custom motion directives, dance rhythm, or scene context"},"aspect_ratio":{"type":"string","enum":["9:16","16:9","1:1"],"default":"9:16"},"duration_seconds":{"type":"integer","default":8},"seamless_loop":{"type":"boolean","default":true},"tier":{"type":"string","enum":["basic","pro"],"default":"basic"},"webhook_url":{"type":"string","format":"uri","description":"Callback URL when video generation completes"}}},"VideoResponse":{"type":"object","properties":{"video_id":{"type":"string"},"status":{"type":"string","enum":["pending","running","completed","failed"]},"preset":{"type":"string"},"camera_motion":{"type":"string"},"motion_intensity":{"type":"string"},"aspect_ratio":{"type":"string"},"duration_seconds":{"type":"integer"},"credits_used":{"type":"integer"},"check_url":{"type":"string"},"created_at":{"type":"string"}}},"AccountResponse":{"type":"object","properties":{"user_id":{"type":"string"},"email":{"type":"string"},"plan_tier":{"type":"string"},"credits_balance":{"type":"integer"},"limits":{"type":"object","properties":{"max_personas":{"type":"integer"},"max_batch_size":{"type":"integer"},"allows_pro":{"type":"boolean"},"allows_video":{"type":"boolean"}}}}}}},"security":[{"bearerAuth":[]},{"apiKeyAuth":[]}],"paths":{"/api/v1/personas":{"get":{"summary":"List AI Personas","description":"Lists all identity-locked AI influencer personas owned by the authenticated bot.","responses":{"200":{"description":"Array of persona objects","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Persona"}}}}},"401":{"description":"Unauthorized"}}},"post":{"summary":"Create AI Persona","description":"Creates and registers a new AI persona with biometric consistency descriptors.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePersonaInput"}}}},"responses":{"201":{"description":"Created persona","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Persona"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Persona limit reached"}}}},"/api/v1/shoots":{"post":{"summary":"Launch Photoshoot Batch","description":"Generates identity-consistent variations of a persona across selected aspect ratios.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShootInput"}}}},"responses":{"201":{"description":"Photoshoot started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShootResponse"}}}},"401":{"description":"Unauthorized"},"402":{"description":"Insufficient credits"}}}},"/api/v1/shoots/{id}":{"get":{"summary":"Get Photoshoot Status & Image URLs","description":"Retrieves status and final generated image URLs for a batch photoshoot.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The shoot_id returned from POST /api/v1/shoots"}],"responses":{"200":{"description":"Photoshoot details with variations"},"404":{"description":"Shoot not found"}}}},"/api/v1/videos":{"get":{"summary":"List Generated Videos","description":"Lists recent animated portrait, dance, and UGC videos generated for this account.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":20},"description":"Max videos to return"},{"name":"offset","in":"query","schema":{"type":"integer","default":0},"description":"Pagination offset"}],"responses":{"200":{"description":"List of videos"},"401":{"description":"Unauthorized"}}},"post":{"summary":"Generate Video (Dance, UGC, High-Motion)","description":"Animates an existing persona photo into a dynamic short-form video clip with dance, UGC talking, or catwalk motion.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoInput"}}}},"responses":{"201":{"description":"Video generation job started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoResponse"}}}},"400":{"description":"Invalid parameters or missing photo"},"401":{"description":"Unauthorized"},"402":{"description":"Insufficient credits"}}}},"/api/v1/videos/{id}":{"get":{"summary":"Get Video Status & Download URLs","description":"Retrieves the status, MP4 video URL, and thumbnail URL for a generated video clip.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The video_id returned from POST /api/v1/videos"}],"responses":{"200":{"description":"Video status and download URLs"},"404":{"description":"Video not found"}}}},"/api/v1/account":{"get":{"summary":"Get Account & Balance","description":"Returns the current credit balance, plan tier, and compute limits.","responses":{"200":{"description":"Account details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountResponse"}}}},"401":{"description":"Unauthorized"}}}},"/api/v1/account/topup":{"post":{"summary":"Request Top-Up Checkout","description":"Generates a Stripe Checkout session URL for machine-to-machine wallet top-up.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pack_id":{"type":"string","enum":["trial-9","starter-19","creator-39","studio-89"]}},"required":["pack_id"]}}}},"responses":{"200":{"description":"Checkout session created"}}}}}}