{"openapi":"3.1.0","info":{"title":"Pickshot API","version":"1","summary":"Generate AI pictures, short videos, voices, music, sound effects and every website creation feature.","description":"Every model and website-only creation feature on Pickshot through one key. Standard API keys pay credits (prices are in GET /api/v1/models); server-authorized internal operator accounts receive zero-credit generation estimates. there is no free trial and no membership inclusion through the API. Pictures from our own picture models come back in the same response; videos, audio, edits, apps, personas and editor tools are jobs you poll. Sign in and make a key at https://pickshot.ai/developers, where the guide, Python/JavaScript clients and MCP configuration are too. MCP is available at https://pickshot.ai/mcp with the same API key. Website free promotions and membership inclusions do not apply to API/MCP.","contact":{"name":"Pickshot support","url":"https://pickshot.ai/developers"},"termsOfService":"https://pickshot.ai/en/terms"},"servers":[{"url":"https://pickshot.ai"}],"security":[{"bearer":[]}],"externalDocs":{"description":"Developer guide","url":"https://pickshot.ai/developers"},"paths":{"/api/v1/models":{"get":{"operationId":"listModels","summary":"Models, modes, limits and prices","description":"Public: works without a key. With a key it says what that account may use.","security":[{},{"bearer":[]}],"responses":{"200":{"description":"The models","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelList"}}}}}}},"/api/v1/me":{"get":{"operationId":"me","summary":"The key's account: plan, credits and safety tier","responses":{"200":{"description":"The account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}},"401":{"description":"The key is missing, wrong or revoked (invalid_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/gpu/availability":{"get":{"operationId":"getGpuAvailability","summary":"Whether fewer than three GPUs are working","description":"Returns a JSON boolean from the Pickshot queue and worker heartbeats: true for zero, one or two working physical GPUs; false for three or more. Queued jobs are not running GPUs. This is not hardware utilization, a reservation or a model-specific availability guarantee. When state cannot be determined the API returns 503. Requires an API key; no credits are charged.","responses":{"200":{"description":"Current threshold result","content":{"application/json":{"schema":{"type":"boolean"}}}},"401":{"description":"The key is missing, wrong or revoked (invalid_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests or jobs at once (rate_limited, too_many_jobs), or the daily provider budget is full (daily_limit, reason: provider_day_budget; retry_after and Retry-After give seconds until midnight KST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"GPU state cannot be determined (gpu_status_unavailable); retry after the Retry-After interval","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/adult-confirm":{"post":{"operationId":"confirmAdult","summary":"Explicitly confirm the account owner is 19 or older","description":"The owner must explicitly confirm age and the adult-creation undertaking. Never infer this from the prompt. Saves once on the account; web, API, MCP and reference images share that permission. Korea allows tier3 and other known countries tier4 after confirmation (tier2 before it and in unknown countries), with valid operator/coupon exceptions. This does not override prohibited harms or provider restrictions.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"age":{"type":"boolean","const":true}},"required":["age"]}}}},"responses":{"200":{"description":"Confirmation saved"},"400":{"description":"An explicit true confirmation is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The key is missing, wrong or revoked (invalid_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Adult creation unavailable for this account/country","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/gpu/status":{"get":{"operationId":"getGpuStatus","summary":"Measured GPU load and queue counts","description":"Deduplicates live physical GPUs by UUID, includes loading/generating/transfers as busy, excludes CPU workers and distinguishes unavailable cards. busy_ratio is busy GPUs / online GPUs, not hardware SM utilization. Counts only; no worker identifiers or other accounts’ jobs or prompts. A snapshot, not a reservation or model-specific start guarantee.","responses":{"200":{"description":"Measured snapshot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GpuStatus"}}}},"401":{"description":"The key is missing, wrong or revoked (invalid_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"gpu_status_unavailable; retry after 15 seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/estimate":{"post":{"operationId":"estimateCost","summary":"Quote a validated request before generating","description":"Never generates or charges. Quotes current credits. Reference URLs are validated/read when needed. Availability, credits and prices can change; send max_credits on generation. There is no free API trial.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["kind","request"],"properties":{"kind":{"type":"string","enum":["images","videos","audio"]},"request":{"oneOf":[{"$ref":"#/components/schemas/ImageRequest"},{"$ref":"#/components/schemas/VideoRequest"},{"$ref":"#/components/schemas/AudioRequest"}]}}}}}},"responses":{"200":{"description":"The current estimate","content":{"application/json":{"schema":{"type":"object","properties":{"model":{"type":"string"},"mode":{"type":"string"},"billing":{"type":"string","enum":["credits","operator"]},"credits":{"type":"integer","minimum":0},"membership_included":{"const":false}},"required":["model","mode","credits","membership_included"]}}}},"400":{"description":"Something in the body is not accepted (bad_request, bad_model, bad_mode, bad_prompt, bad_ratio, bad_count, bad_seed, bad_voice, bad_image_url, bad_video_url, bad_video, video_length)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The key is missing, wrong or revoked (invalid_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits (no_credits: need, have)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Safety refusal (blocked), adult confirmation required (adult_confirm; POST /api/v1/me/adult-confirm), unavailable in your country (region_unavailable), clip input disabled (input_not_open), or 4K upscale requires Pro/Max (plan_required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request exceeds max_credits (price_changed), reuses a key with another payload (idempotency_conflict), or is still in progress (request_in_progress; retry the same key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Input video exceeds 20 MiB (too_large; max is the byte limit)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests or jobs at once (rate_limited, too_many_jobs), or the daily provider budget is full (daily_limit, reason: provider_day_budget; retry_after and Retry-After give seconds until midnight KST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The model is not open yet (coming_soon), generation is paused, it is busy (busy, with a Retry-After header), or the safety check could not answer just then (safety_unavailable: nothing was taken, send it again)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/images":{"post":{"operationId":"createImage","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{8,128}$"},"description":"One stable unique key per authorized generation, retained 24 hours. Reuse unchanged on retry. A changed payload conflicts; an in-flight request returns 409 request_in_progress. Do not start a new key after an ambiguous timeout."}],"summary":"Make pictures from a prompt, or edit pictures","description":"Our own picture models answer with the pictures (200). With `images` (https links) it is an edit job (202). A retry whose image was accepted but final receipt was lost can also return 202 with the existing id; poll that id without submitting again.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageRequest"}}}},"responses":{"200":{"description":"Done: the pictures","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"202":{"description":"The job (poll GET /api/v1/jobs/{id} until it is done or failed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"description":"Something in the body is not accepted (bad_request, bad_model, bad_mode, bad_prompt, bad_ratio, bad_count, bad_seed, bad_voice, bad_image_url, bad_video_url, bad_video, video_length)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The key is missing, wrong or revoked (invalid_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits (no_credits: need, have)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Safety refusal (blocked), adult confirmation required (adult_confirm; POST /api/v1/me/adult-confirm), unavailable in your country (region_unavailable), clip input disabled (input_not_open), or 4K upscale requires Pro/Max (plan_required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request exceeds max_credits (price_changed), reuses a key with another payload (idempotency_conflict), or is still in progress (request_in_progress; retry the same key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Input video exceeds 20 MiB (too_large; max is the byte limit)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests or jobs at once (rate_limited, too_many_jobs), or the daily provider budget is full (daily_limit, reason: provider_day_budget; retry_after and Retry-After give seconds until midnight KST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The model is not open yet (coming_soon), generation is paused, it is busy (busy, with a Retry-After header), or the safety check could not answer just then (safety_unavailable: nothing was taken, send it again)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/videos":{"post":{"operationId":"createVideo","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{8,128}$"},"description":"One stable unique key per authorized generation, retained 24 hours. Reuse unchanged on retry. A changed payload conflicts; an in-flight request returns 409 request_in_progress. Do not start a new key after an ambiguous timeout."}],"summary":"Generate a short video or upscale an existing MP4","description":"For upscaling, use model tool-video-upscale (Real-ESRGAN, up to 30 seconds) or tool-video-upscale-pro (SeedVR2-7B temporal restoration, up to 10 seconds at 1080p or 3 seconds at 4K, up to 30 fps), mode vupscale and video_url. The public HTTPS MP4 is fetched and validated (20 MiB, up to 30 seconds), then copied to a temporary private input for the own-GPU processor. Select 1080p or 4K (Pro/Max). Billed seconds are rounded up from the MP4 header, never supplied seconds. Original audio is preserved. Estimate first, submit with max_credits and a stable Idempotency-Key, then poll the returned job id.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoRequest"}}}},"responses":{"202":{"description":"The job (poll GET /api/v1/jobs/{id} until it is done or failed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"description":"Something in the body is not accepted (bad_request, bad_model, bad_mode, bad_prompt, bad_ratio, bad_count, bad_seed, bad_voice, bad_image_url, bad_video_url, bad_video, video_length)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The key is missing, wrong or revoked (invalid_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits (no_credits: need, have)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Safety refusal (blocked), adult confirmation required (adult_confirm; POST /api/v1/me/adult-confirm), unavailable in your country (region_unavailable), clip input disabled (input_not_open), or 4K upscale requires Pro/Max (plan_required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request exceeds max_credits (price_changed), reuses a key with another payload (idempotency_conflict), or is still in progress (request_in_progress; retry the same key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Input video exceeds 20 MiB (too_large; max is the byte limit)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests or jobs at once (rate_limited, too_many_jobs), or the daily provider budget is full (daily_limit, reason: provider_day_budget; retry_after and Retry-After give seconds until midnight KST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The model is not open yet (coming_soon), generation is paused, it is busy (busy, with a Retry-After header), or the safety check could not answer just then (safety_unavailable: nothing was taken, send it again)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/audio":{"post":{"operationId":"createAudio","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{8,128}$"},"description":"One stable unique key per authorized generation, retained 24 hours. Reuse unchanged on retry. A changed payload conflicts; an in-flight request returns 409 request_in_progress. Do not start a new key after an ambiguous timeout."}],"summary":"Speech from text, music or a sound effect","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AudioRequest"}}}},"responses":{"202":{"description":"The job (poll GET /api/v1/jobs/{id} until it is done or failed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"description":"Something in the body is not accepted (bad_request, bad_model, bad_mode, bad_prompt, bad_ratio, bad_count, bad_seed, bad_voice, bad_image_url, bad_video_url, bad_video, video_length)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The key is missing, wrong or revoked (invalid_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits (no_credits: need, have)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Safety refusal (blocked), adult confirmation required (adult_confirm; POST /api/v1/me/adult-confirm), unavailable in your country (region_unavailable), clip input disabled (input_not_open), or 4K upscale requires Pro/Max (plan_required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request exceeds max_credits (price_changed), reuses a key with another payload (idempotency_conflict), or is still in progress (request_in_progress; retry the same key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Input video exceeds 20 MiB (too_large; max is the byte limit)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests or jobs at once (rate_limited, too_many_jobs), or the daily provider budget is full (daily_limit, reason: provider_day_budget; retry_after and Retry-After give seconds until midnight KST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The model is not open yet (coming_soon), generation is paused, it is busy (busy, with a Retry-After header), or the safety check could not answer just then (safety_unavailable: nothing was taken, send it again)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/features":{"get":{"operationId":"listFeatures","summary":"Website creation features, their endpoints and credit prices","description":"Public. Photo apps, characters, personas and campaign planning, song lyrics, the video editor AI tools and the agent. Menu prices are in credits per run; the exact model price of a post is the model list price.","responses":{"200":{"description":"Feature list","content":{"application/json":{"schema":{"type":"object","properties":{"features":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}}}}},"/api/v1/apps":{"get":{"operationId":"listApps","summary":"Photo apps and character builders","description":"Public. Each app names its options and field ids; POST the same multipart form the website uses. Every app run costs 29 credits through the API.","responses":{"200":{"description":"Apps","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppList"}}}}}}},"/api/v1/apps/{id}":{"get":{"operationId":"getApp","summary":"One app and its form fields","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The app","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"No such app (not_found)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createAppRun","summary":"Run a photo app (29 credits)","description":"multipart/form-data: image, image2 for two-photo apps, option (an id from GET /api/v1/apps), fields (JSON object keyed by field key). Face/character swap require both photos and are available only in enabled markets. Outfit swap may use a description instead of image2. A successful run returns {job}; poll GET /api/v1/jobs/{job.id}. This fixed-price endpoint does not implement max_credits or Idempotency-Key; do not automatically retry after an ambiguous timeout.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"image":{"type":"string","format":"binary"},"image2":{"type":"string","format":"binary"},"option":{"type":"string"},"fields":{"type":"string","description":"JSON object; put free text in fields.prompt when the app declares that field"}}}}}},"responses":{"200":{"description":"The accepted job","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Something in the body is not accepted (bad_request, bad_model, bad_mode, bad_prompt, bad_ratio, bad_count, bad_seed, bad_voice, bad_image_url, bad_video_url, bad_video, video_length)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The key is missing, wrong or revoked (invalid_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits (no_credits: need, have)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Safety refusal (blocked), adult confirmation required (adult_confirm; POST /api/v1/me/adult-confirm), unavailable in your country (region_unavailable), clip input disabled (input_not_open), or 4K upscale requires Pro/Max (plan_required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request exceeds max_credits (price_changed), reuses a key with another payload (idempotency_conflict), or is still in progress (request_in_progress; retry the same key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Input video exceeds 20 MiB (too_large; max is the byte limit)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Send multipart/form-data (multipart_required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests or jobs at once (rate_limited, too_many_jobs), or the daily provider budget is full (daily_limit, reason: provider_day_budget; retry_after and Retry-After give seconds until midnight KST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The model is not open yet (coming_soon), generation is paused, it is busy (busy, with a Retry-After header), or the safety check could not answer just then (safety_unavailable: nothing was taken, send it again)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/apps/video-reenactment":{"get":{"operationId":"getVideoReenactment","summary":"Motion app settings and sample characters","responses":{"200":{"description":"Settings","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"The key is missing, wrong or revoked (invalid_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createVideoReenactment","summary":"Run the motion app (quoted per second)","description":"Quote first at GET /api/v1/apps/video-reenactment/quote?seconds=...&resolution=.... Send multipart/form-data with video (MP4), image (JPEG/PNG), or sampleId/personaId, resolution, optional prompt, requestKey (8-80 letters, digits, _ or -), and all three quote fields: maxCredits, quotedFor, quotedUntil. Actual duration is measured from the uploaded MP4, not a seconds form field. Returns {job}; poll GET /api/v1/jobs/{job.id}. Reuse the same requestKey and input files after a timeout; an expired quote must be refreshed.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/VideoReenactmentRequest"}}}},"responses":{"200":{"description":"The accepted job","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Something in the body is not accepted (bad_request, bad_model, bad_mode, bad_prompt, bad_ratio, bad_count, bad_seed, bad_voice, bad_image_url, bad_video_url, bad_video, video_length)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The key is missing, wrong or revoked (invalid_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits (no_credits: need, have)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Safety refusal (blocked), adult confirmation required (adult_confirm; POST /api/v1/me/adult-confirm), unavailable in your country (region_unavailable), clip input disabled (input_not_open), or 4K upscale requires Pro/Max (plan_required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request exceeds max_credits (price_changed), reuses a key with another payload (idempotency_conflict), or is still in progress (request_in_progress; retry the same key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Input video exceeds 20 MiB (too_large; max is the byte limit)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests or jobs at once (rate_limited, too_many_jobs), or the daily provider budget is full (daily_limit, reason: provider_day_budget; retry_after and Retry-After give seconds until midnight KST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The model is not open yet (coming_soon), generation is paused, it is busy (busy, with a Retry-After header), or the safety check could not answer just then (safety_unavailable: nothing was taken, send it again)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/apps/video-reenactment/quote":{"get":{"operationId":"quoteVideoReenactment","summary":"Quote the motion app by resolution and seconds","parameters":[{"name":"resolution","in":"query","schema":{"type":"string","enum":["720p","1080p"]}},{"name":"seconds","in":"query","schema":{"type":"number"}}],"responses":{"200":{"description":"The quote (maxCredits, quotedFor, quotedUntil, seconds, resolution)","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Something in the body is not accepted (bad_request, bad_model, bad_mode, bad_prompt, bad_ratio, bad_count, bad_seed, bad_voice, bad_image_url, bad_video_url, bad_video, video_length)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The key is missing, wrong or revoked (invalid_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Safety refusal (blocked), adult confirmation required (adult_confirm; POST /api/v1/me/adult-confirm), unavailable in your country (region_unavailable), clip input disabled (input_not_open), or 4K upscale requires Pro/Max (plan_required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The model is not open yet (coming_soon), generation is paused, it is busy (busy, with a Retry-After header), or the safety check could not answer just then (safety_unavailable: nothing was taken, send it again)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/characters":{"get":{"operationId":"listCharacters","summary":"Saved characters of the key owner","responses":{"200":{"description":"Characters","content":{"application/json":{"schema":{"type":"object","properties":{"characters":{"type":"array","items":{"$ref":"#/components/schemas/Character"}}}}}}},"401":{"description":"The key is missing, wrong or revoked (invalid_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createCharacter","summary":"Save a character reference","description":"multipart/form-data: name, description, one to three images (or fromImage/fromKey owned by the account). Saving a reference is free; the plan limit applies. Use its /i/ links in a later edit.","responses":{"200":{"description":"The character id","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"}}}}}},"400":{"description":"Something in the body is not accepted (bad_request, bad_model, bad_mode, bad_prompt, bad_ratio, bad_count, bad_seed, bad_voice, bad_image_url, bad_video_url, bad_video, video_length)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The key is missing, wrong or revoked (invalid_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits (no_credits: need, have)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Safety refusal (blocked), adult confirmation required (adult_confirm; POST /api/v1/me/adult-confirm), unavailable in your country (region_unavailable), clip input disabled (input_not_open), or 4K upscale requires Pro/Max (plan_required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request exceeds max_credits (price_changed), reuses a key with another payload (idempotency_conflict), or is still in progress (request_in_progress; retry the same key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Input video exceeds 20 MiB (too_large; max is the byte limit)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Send multipart/form-data (multipart_required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests or jobs at once (rate_limited, too_many_jobs), or the daily provider budget is full (daily_limit, reason: provider_day_budget; retry_after and Retry-After give seconds until midnight KST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The model is not open yet (coming_soon), generation is paused, it is busy (busy, with a Retry-After header), or the safety check could not answer just then (safety_unavailable: nothing was taken, send it again)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/characters/{id}":{"delete":{"operationId":"deleteCharacter","summary":"Delete a saved character","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted"},"401":{"description":"The key is missing, wrong or revoked (invalid_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/personas":{"get":{"operationId":"listPersonas","summary":"AI influencer personas","responses":{"200":{"description":"Personas","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"The key is missing, wrong or revoked (invalid_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createPersona","summary":"Save a persona (free; plan limit applies)","description":"multipart/form-data: name, bio, niche (0-7), platform (0-4), face (a photo) or characterId or sampleId, voicePreset.","responses":{"200":{"description":"The persona","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Something in the body is not accepted (bad_request, bad_model, bad_mode, bad_prompt, bad_ratio, bad_count, bad_seed, bad_voice, bad_image_url, bad_video_url, bad_video, video_length)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The key is missing, wrong or revoked (invalid_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits (no_credits: need, have)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Safety refusal (blocked), adult confirmation required (adult_confirm; POST /api/v1/me/adult-confirm), unavailable in your country (region_unavailable), clip input disabled (input_not_open), or 4K upscale requires Pro/Max (plan_required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request exceeds max_credits (price_changed), reuses a key with another payload (idempotency_conflict), or is still in progress (request_in_progress; retry the same key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Input video exceeds 20 MiB (too_large; max is the byte limit)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests or jobs at once (rate_limited, too_many_jobs), or the daily provider budget is full (daily_limit, reason: provider_day_budget; retry_after and Retry-After give seconds until midnight KST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The model is not open yet (coming_soon), generation is paused, it is busy (busy, with a Retry-After header), or the safety check could not answer just then (safety_unavailable: nothing was taken, send it again)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/personas/{id}":{"patch":{"operationId":"updatePersona","summary":"Update a persona","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The persona","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Something in the body is not accepted (bad_request, bad_model, bad_mode, bad_prompt, bad_ratio, bad_count, bad_seed, bad_voice, bad_image_url, bad_video_url, bad_video, video_length)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The key is missing, wrong or revoked (invalid_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits (no_credits: need, have)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Safety refusal (blocked), adult confirmation required (adult_confirm; POST /api/v1/me/adult-confirm), unavailable in your country (region_unavailable), clip input disabled (input_not_open), or 4K upscale requires Pro/Max (plan_required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request exceeds max_credits (price_changed), reuses a key with another payload (idempotency_conflict), or is still in progress (request_in_progress; retry the same key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Input video exceeds 20 MiB (too_large; max is the byte limit)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests or jobs at once (rate_limited, too_many_jobs), or the daily provider budget is full (daily_limit, reason: provider_day_budget; retry_after and Retry-After give seconds until midnight KST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The model is not open yet (coming_soon), generation is paused, it is busy (busy, with a Retry-After header), or the safety check could not answer just then (safety_unavailable: nothing was taken, send it again)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deletePersona","summary":"Delete a persona","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted"},"401":{"description":"The key is missing, wrong or revoked (invalid_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/personas/{id}/campaigns":{"get":{"operationId":"listCampaigns","summary":"Campaigns of a persona","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Campaigns","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"The key is missing, wrong or revoked (invalid_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"planCampaign","summary":"Plan a content campaign (20 credits)","description":"JSON: brief, goal, language, count, startDate, manual?, requestKey. The planner writes the series; manual=true creates an empty campaign for no charge. API price: 20 credits.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["brief","startDate","requestKey"],"properties":{"brief":{"type":"string"},"goal":{"type":"string"},"language":{"type":"string"},"count":{"type":"integer"},"startDate":{"type":"string"},"manual":{"type":"boolean"},"requestKey":{"type":"string"}}}}}},"responses":{"200":{"description":"The campaign","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Something in the body is not accepted (bad_request, bad_model, bad_mode, bad_prompt, bad_ratio, bad_count, bad_seed, bad_voice, bad_image_url, bad_video_url, bad_video, video_length)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The key is missing, wrong or revoked (invalid_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits (no_credits: need, have)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Safety refusal (blocked), adult confirmation required (adult_confirm; POST /api/v1/me/adult-confirm), unavailable in your country (region_unavailable), clip input disabled (input_not_open), or 4K upscale requires Pro/Max (plan_required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request exceeds max_credits (price_changed), reuses a key with another payload (idempotency_conflict), or is still in progress (request_in_progress; retry the same key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Input video exceeds 20 MiB (too_large; max is the byte limit)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests or jobs at once (rate_limited, too_many_jobs), or the daily provider budget is full (daily_limit, reason: provider_day_budget; retry_after and Retry-After give seconds until midnight KST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The model is not open yet (coming_soon), generation is paused, it is busy (busy, with a Retry-After header), or the safety check could not answer just then (safety_unavailable: nothing was taken, send it again)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/personas/{id}/campaigns/{campaign}":{"get":{"operationId":"getCampaign","summary":"One campaign with its posts","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"campaign","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The campaign","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteCampaign","summary":"Delete a campaign","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"campaign","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted"},"401":{"description":"The key is missing, wrong or revoked (invalid_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/personas/{id}/campaigns/{campaign}/posts":{"post":{"operationId":"addPost","summary":"Add a draft post","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"campaign","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The campaign","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Something in the body is not accepted (bad_request, bad_model, bad_mode, bad_prompt, bad_ratio, bad_count, bad_seed, bad_voice, bad_image_url, bad_video_url, bad_video, video_length)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The key is missing, wrong or revoked (invalid_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits (no_credits: need, have)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Safety refusal (blocked), adult confirmation required (adult_confirm; POST /api/v1/me/adult-confirm), unavailable in your country (region_unavailable), clip input disabled (input_not_open), or 4K upscale requires Pro/Max (plan_required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request exceeds max_credits (price_changed), reuses a key with another payload (idempotency_conflict), or is still in progress (request_in_progress; retry the same key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Input video exceeds 20 MiB (too_large; max is the byte limit)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests or jobs at once (rate_limited, too_many_jobs), or the daily provider budget is full (daily_limit, reason: provider_day_budget; retry_after and Retry-After give seconds until midnight KST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The model is not open yet (coming_soon), generation is paused, it is busy (busy, with a Retry-After header), or the safety check could not answer just then (safety_unavailable: nothing was taken, send it again)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/personas/{id}/campaigns/{campaign}/reuse":{"post":{"operationId":"reuseCampaign","summary":"Copy a campaign to a new start date","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"campaign","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The new campaign","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Something in the body is not accepted (bad_request, bad_model, bad_mode, bad_prompt, bad_ratio, bad_count, bad_seed, bad_voice, bad_image_url, bad_video_url, bad_video, video_length)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The key is missing, wrong or revoked (invalid_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits (no_credits: need, have)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Safety refusal (blocked), adult confirmation required (adult_confirm; POST /api/v1/me/adult-confirm), unavailable in your country (region_unavailable), clip input disabled (input_not_open), or 4K upscale requires Pro/Max (plan_required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request exceeds max_credits (price_changed), reuses a key with another payload (idempotency_conflict), or is still in progress (request_in_progress; retry the same key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Input video exceeds 20 MiB (too_large; max is the byte limit)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests or jobs at once (rate_limited, too_many_jobs), or the daily provider budget is full (daily_limit, reason: provider_day_budget; retry_after and Retry-After give seconds until midnight KST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The model is not open yet (coming_soon), generation is paused, it is busy (busy, with a Retry-After header), or the safety check could not answer just then (safety_unavailable: nothing was taken, send it again)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/personas/{id}/posts/{post}":{"patch":{"operationId":"updatePost","summary":"Edit a draft post","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"post","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The campaign","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Something in the body is not accepted (bad_request, bad_model, bad_mode, bad_prompt, bad_ratio, bad_count, bad_seed, bad_voice, bad_image_url, bad_video_url, bad_video, video_length)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The key is missing, wrong or revoked (invalid_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits (no_credits: need, have)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Safety refusal (blocked), adult confirmation required (adult_confirm; POST /api/v1/me/adult-confirm), unavailable in your country (region_unavailable), clip input disabled (input_not_open), or 4K upscale requires Pro/Max (plan_required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request exceeds max_credits (price_changed), reuses a key with another payload (idempotency_conflict), or is still in progress (request_in_progress; retry the same key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Input video exceeds 20 MiB (too_large; max is the byte limit)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests or jobs at once (rate_limited, too_many_jobs), or the daily provider budget is full (daily_limit, reason: provider_day_budget; retry_after and Retry-After give seconds until midnight KST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The model is not open yet (coming_soon), generation is paused, it is busy (busy, with a Retry-After header), or the safety check could not answer just then (safety_unavailable: nothing was taken, send it again)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deletePost","summary":"Delete a post","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"post","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The campaign","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"The key is missing, wrong or revoked (invalid_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/personas/{id}/posts/{post}/generate":{"post":{"operationId":"generatePersonaPost","summary":"Make a persona post picture (model price)","description":"Submits the post as an edit job from the persona face. Returns {jobId}; poll GET /api/v1/jobs/{jobId}. Deduplicated by the owned post id on the server, independent of Idempotency-Key. A new version requires a new draft. The API price is the edit model price; memberships do not include it.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"post","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The accepted job","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Something in the body is not accepted (bad_request, bad_model, bad_mode, bad_prompt, bad_ratio, bad_count, bad_seed, bad_voice, bad_image_url, bad_video_url, bad_video, video_length)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The key is missing, wrong or revoked (invalid_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits (no_credits: need, have)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Safety refusal (blocked), adult confirmation required (adult_confirm; POST /api/v1/me/adult-confirm), unavailable in your country (region_unavailable), clip input disabled (input_not_open), or 4K upscale requires Pro/Max (plan_required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request exceeds max_credits (price_changed), reuses a key with another payload (idempotency_conflict), or is still in progress (request_in_progress; retry the same key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Input video exceeds 20 MiB (too_large; max is the byte limit)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests or jobs at once (rate_limited, too_many_jobs), or the daily provider budget is full (daily_limit, reason: provider_day_budget; retry_after and Retry-After give seconds until midnight KST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The model is not open yet (coming_soon), generation is paused, it is busy (busy, with a Retry-After header), or the safety check could not answer just then (safety_unavailable: nothing was taken, send it again)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/personas/{id}/identity":{"put":{"operationId":"updatePersonaIdentity","summary":"Save the persona identity bible","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The identity","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Something in the body is not accepted (bad_request, bad_model, bad_mode, bad_prompt, bad_ratio, bad_count, bad_seed, bad_voice, bad_image_url, bad_video_url, bad_video, video_length)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The key is missing, wrong or revoked (invalid_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits (no_credits: need, have)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Safety refusal (blocked), adult confirmation required (adult_confirm; POST /api/v1/me/adult-confirm), unavailable in your country (region_unavailable), clip input disabled (input_not_open), or 4K upscale requires Pro/Max (plan_required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request exceeds max_credits (price_changed), reuses a key with another payload (idempotency_conflict), or is still in progress (request_in_progress; retry the same key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Input video exceeds 20 MiB (too_large; max is the byte limit)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests or jobs at once (rate_limited, too_many_jobs), or the daily provider budget is full (daily_limit, reason: provider_day_budget; retry_after and Retry-After give seconds until midnight KST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The model is not open yet (coming_soon), generation is paused, it is busy (busy, with a Retry-After header), or the safety check could not answer just then (safety_unavailable: nothing was taken, send it again)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/song/lyrics":{"post":{"operationId":"writeLyrics","summary":"Write original song lyrics (8 credits)","description":"JSON: idea, lang (ko/ja/zh/en), genre, moods, voice, length. Returns title and lyrics with section tags. The site song maker stays free; API calls are paid.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["idea"],"properties":{"idea":{"type":"string"},"lang":{"type":"string","enum":["ko","ja","zh","en"]},"genre":{"type":"string"},"moods":{"type":"array","items":{"type":"string"}},"voice":{"type":"string"},"length":{"type":"string"}}}}}},"responses":{"200":{"description":"Title and lyrics","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Something in the body is not accepted (bad_request, bad_model, bad_mode, bad_prompt, bad_ratio, bad_count, bad_seed, bad_voice, bad_image_url, bad_video_url, bad_video, video_length)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The key is missing, wrong or revoked (invalid_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits (no_credits: need, have)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Safety refusal (blocked), adult confirmation required (adult_confirm; POST /api/v1/me/adult-confirm), unavailable in your country (region_unavailable), clip input disabled (input_not_open), or 4K upscale requires Pro/Max (plan_required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request exceeds max_credits (price_changed), reuses a key with another payload (idempotency_conflict), or is still in progress (request_in_progress; retry the same key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Input video exceeds 20 MiB (too_large; max is the byte limit)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests or jobs at once (rate_limited, too_many_jobs), or the daily provider budget is full (daily_limit, reason: provider_day_budget; retry_after and Retry-After give seconds until midnight KST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The model is not open yet (coming_soon), generation is paused, it is busy (busy, with a Retry-After header), or the safety check could not answer just then (safety_unavailable: nothing was taken, send it again)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/editor/transcribe":{"post":{"operationId":"transcribeClip","summary":"Transcribe a clip's sound (4 credits a started minute)","description":"Send a 16 kHz mono WAV (audio/wav) as the request body; the lang query is optional (ko/ja/zh/en). Returns an edit job to poll.","requestBody":{"required":true,"content":{"audio/wav":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"The transcription job","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Something in the body is not accepted (bad_request, bad_model, bad_mode, bad_prompt, bad_ratio, bad_count, bad_seed, bad_voice, bad_image_url, bad_video_url, bad_video, video_length)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The key is missing, wrong or revoked (invalid_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits (no_credits: need, have)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Safety refusal (blocked), adult confirmation required (adult_confirm; POST /api/v1/me/adult-confirm), unavailable in your country (region_unavailable), clip input disabled (input_not_open), or 4K upscale requires Pro/Max (plan_required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request exceeds max_credits (price_changed), reuses a key with another payload (idempotency_conflict), or is still in progress (request_in_progress; retry the same key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Input video exceeds 20 MiB (too_large; max is the byte limit)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests or jobs at once (rate_limited, too_many_jobs), or the daily provider budget is full (daily_limit, reason: provider_day_budget; retry_after and Retry-After give seconds until midnight KST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The model is not open yet (coming_soon), generation is paused, it is busy (busy, with a Retry-After header), or the safety check could not answer just then (safety_unavailable: nothing was taken, send it again)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/editor/transcribe/{id}":{"get":{"operationId":"getTranscription","summary":"A transcription job and its words","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The job","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"The key is missing, wrong or revoked (invalid_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/editor/transcribe/{id}/cancel":{"post":{"operationId":"cancelTranscription","summary":"Stop a transcription and refund its credits","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Canceled"},"401":{"description":"The key is missing, wrong or revoked (invalid_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/editor/plan":{"post":{"operationId":"planEdit","summary":"Plan an AI cut from a transcript (20 credits)","description":"JSON: transcript (an id from /api/v1/editor/transcribe), goal (tidy/short), target seconds, ui language, within word ranges. Returns cuts and captions as word index ranges.","responses":{"200":{"description":"The plan","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Something in the body is not accepted (bad_request, bad_model, bad_mode, bad_prompt, bad_ratio, bad_count, bad_seed, bad_voice, bad_image_url, bad_video_url, bad_video, video_length)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The key is missing, wrong or revoked (invalid_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits (no_credits: need, have)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Safety refusal (blocked), adult confirmation required (adult_confirm; POST /api/v1/me/adult-confirm), unavailable in your country (region_unavailable), clip input disabled (input_not_open), or 4K upscale requires Pro/Max (plan_required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request exceeds max_credits (price_changed), reuses a key with another payload (idempotency_conflict), or is still in progress (request_in_progress; retry the same key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Input video exceeds 20 MiB (too_large; max is the byte limit)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests or jobs at once (rate_limited, too_many_jobs), or the daily provider budget is full (daily_limit, reason: provider_day_budget; retry_after and Retry-After give seconds until midnight KST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The model is not open yet (coming_soon), generation is paused, it is busy (busy, with a Retry-After header), or the safety check could not answer just then (safety_unavailable: nothing was taken, send it again)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agent/chat":{"post":{"operationId":"agentChat","summary":"Ask the creative agent for prompts (4 credits)","description":"JSON: messages (last 12 turns), locale. Returns a reply and ready-to-use prompt actions. The agent makes nothing itself.","responses":{"200":{"description":"Reply and actions","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Something in the body is not accepted (bad_request, bad_model, bad_mode, bad_prompt, bad_ratio, bad_count, bad_seed, bad_voice, bad_image_url, bad_video_url, bad_video, video_length)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The key is missing, wrong or revoked (invalid_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits (no_credits: need, have)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Safety refusal (blocked), adult confirmation required (adult_confirm; POST /api/v1/me/adult-confirm), unavailable in your country (region_unavailable), clip input disabled (input_not_open), or 4K upscale requires Pro/Max (plan_required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request exceeds max_credits (price_changed), reuses a key with another payload (idempotency_conflict), or is still in progress (request_in_progress; retry the same key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Input video exceeds 20 MiB (too_large; max is the byte limit)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests or jobs at once (rate_limited, too_many_jobs), or the daily provider budget is full (daily_limit, reason: provider_day_budget; retry_after and Retry-After give seconds until midnight KST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The model is not open yet (coming_soon), generation is paused, it is busy (busy, with a Retry-After header), or the safety check could not answer just then (safety_unavailable: nothing was taken, send it again)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/jobs/{id}":{"get":{"operationId":"getJob","summary":"A job's state and results","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"401":{"description":"The key is missing, wrong or revoked (invalid_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such job for this key (not_found)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Authorization: Bearer ps_live_…"}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true},"VideoReenactmentRequest":{"type":"object","required":["video","resolution","requestKey","maxCredits","quotedFor","quotedUntil"],"anyOf":[{"required":["image"]},{"required":["sampleId"]},{"required":["personaId"]}],"not":{"required":["sampleId","personaId"]},"properties":{"video":{"type":"string","format":"binary","description":"MP4, up to 16 MiB, 3-30 seconds (Free: up to 5 seconds)"},"image":{"type":"string","format":"binary","description":"JPEG or PNG, up to 6 MiB"},"sampleId":{"type":"string","description":"Sample id from GET /api/v1/apps/video-reenactment; omit personaId"},"personaId":{"type":"string","description":"An owned persona; omit sampleId"},"resolution":{"type":"string","enum":["720p","1080p"]},"prompt":{"type":"string","maxLength":1200},"requestKey":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,80}$"},"maxCredits":{"type":"integer","minimum":0,"description":"Copy from the quote"},"quotedFor":{"type":"string","description":"Copy from the quote; must match the key owner"},"quotedUntil":{"type":"integer","description":"Copy from the quote; expiry in Unix milliseconds"}}},"GpuStatus":{"type":"object","required":["measured_at","known","online_gpus","busy_gpus","idle_gpus","unavailable_gpus","queued_jobs","busy_ratio","availability","threshold_busy_gpus"],"properties":{"measured_at":{"type":"integer","description":"Unix milliseconds"},"known":{"const":true},"online_gpus":{"type":"integer","minimum":1},"busy_gpus":{"type":"integer","minimum":0},"idle_gpus":{"type":"integer","minimum":0},"unavailable_gpus":{"type":"integer","minimum":0},"queued_jobs":{"type":"integer","minimum":0},"busy_ratio":{"type":"number","minimum":0,"maximum":1},"availability":{"type":"boolean","description":"Legacy threshold: fewer than 3 working GPUs"},"threshold_busy_gpus":{"const":3}}},"Me":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"handle":{"type":["string","null"]},"plan":{"type":"string","enum":["free","plus","pro","max"]},"safety":{"type":"object","properties":{"tier":{"type":"integer","enum":[2,3,4]},"eligibleTier":{"type":"integer","enum":[2,3,4]},"adultConfirmed":{"type":"boolean"},"confirmationRequired":{"type":"boolean"},"references":{"const":"same_policy"}}},"credits":{"type":"integer"},"billing":{"type":"string","enum":["credits","operator"]},"generation_unlimited":{"type":"boolean","description":"Server-authorized operator account; input/model/safety constraints remain."}}},"ModelList":{"type":"object","properties":{"models":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"pass this as `model`"},"name":{"type":"string"},"maker":{"type":"string"},"type":{"type":"string","enum":["image","video","audio"]},"group":{"type":"string"},"own":{"type":"boolean","description":"a Pickshot-series model"},"modes":{"type":"array","items":{"type":"string","enum":["t2i","edit","removebg","upscale","t2v","i2v","ref2v","v2v","vupscale","interp","tts","music","sfx"]}},"available":{"type":"boolean"},"limits":{"type":"object","additionalProperties":true,"description":"per mode: ratios, resolutions, seconds, max_count…"},"credits":{"type":"object","properties":{"amount":{"type":"number"},"per":{"type":"string"},"from":{"type":"boolean"}}},"site":{"type":"object","description":"what the site asks for the same model","additionalProperties":true}}}}}},"ImageRequest":{"type":"object","required":["model"],"properties":{"max_credits":{"type":"integer","minimum":0,"description":"Maximum authorized charge. A higher actual price returns 409 before charging; obtain a fresh estimate first."},"model":{"type":"string"},"mode":{"type":"string","enum":["t2i","edit","removebg","upscale"],"description":"Inferred from the model or from images when omitted."},"prompt":{"type":"string","maxLength":1500},"ratio":{"type":"string","examples":["1:1","3:4","9:16","16:9"]},"count":{"type":"integer","minimum":1},"seed":{"type":"integer","minimum":0},"negative":{"type":"string","maxLength":500},"resolution":{"type":"string","enum":["1K","2K","4K"],"description":"Use the selected model limits; synchronous GPU/Workers AI pictures currently take 1K."},"images":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":4,"description":"Public HTTPS reference images. Supported Workers AI references complete synchronously; provider edits are jobs."},"image_url":{"type":"string","format":"uri","description":"Single reference image, cut-out or upscale input, when supported by the model."},"bg":{"type":"string","enum":["clear","white","color"],"description":"removebg: background of the cut-out"},"color":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$","description":"removebg with bg=color"},"scale":{"type":"integer","enum":[2,4],"description":"upscale factor"}}},"VideoRequest":{"type":"object","required":["model"],"properties":{"max_credits":{"type":"integer","minimum":0,"description":"Maximum authorized charge. A higher actual price returns 409 before charging; obtain a fresh estimate first."},"model":{"type":"string"},"mode":{"type":"string","enum":["t2v","i2v","ref2v","v2v","vupscale","interp","sfx"]},"prompt":{"type":"string","maxLength":2500},"image_url":{"type":"string","format":"uri","description":"first frame (i2v)"},"end_image_url":{"type":"string","format":"uri"},"images":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":4},"video_url":{"type":"string","format":"uri","maxLength":8192,"description":"video-to-video and the clip tools (vupscale, interp, sfx): publicly downloadable HTTPS MP4, up to 20 MiB. v2v: the model limits apply and the clip is copied to a private temporary input. Real-ESRGAN upscale: up to 30 seconds. SeedVR2: 10 seconds at 1080p or 3 seconds at 4K, up to 30 fps. interp: up to 60 seconds. sfx: up to 60 seconds. Signed CDN URLs are supported; cookies and custom download headers are not. The processor receives a temporary Pickshot copy."},"seconds":{"type":"number","description":"Generation duration. For vupscale, ignored: billing uses the rounded-up duration measured from the MP4."},"resolution":{"type":"string","examples":["480p","720p","1080p","4K"],"description":"For vupscale, 1080p (default) or 4K; 4K requires Pro/Max."},"ratio":{"type":"string"},"sound":{"type":"boolean"},"seed":{"type":"integer","minimum":0},"sound_mode":{"type":"string","enum":["add","replace"],"description":"sfx: keep the clip sound under the new one, or replace it"}},"allOf":[{"if":{"properties":{"mode":{"const":"v2v"}},"required":["mode"]},"then":{"required":["video_url"]}},{"if":{"properties":{"model":{"enum":["tool-video-upscale","tool-video-upscale-pro"]}},"required":["model"]},"then":{"required":["video_url"],"properties":{"mode":{"const":"vupscale"},"resolution":{"enum":["1080p","4K"]}}}},{"if":{"properties":{"model":{"const":"tool-interp"}},"required":["model"]},"then":{"required":["video_url"],"properties":{"mode":{"const":"interp"}}}},{"if":{"properties":{"model":{"const":"tool-sfx"}},"required":["model"]},"then":{"required":["video_url","prompt"],"properties":{"mode":{"const":"sfx"}}}}]},"AudioRequest":{"type":"object","required":["model"],"properties":{"max_credits":{"type":"integer","minimum":0,"description":"Maximum authorized charge. A higher actual price returns 409 before charging; obtain a fresh estimate first."},"model":{"type":"string"},"mode":{"type":"string","enum":["tts","clone","music","sfx"]},"audio_url":{"type":"string","format":"uri","description":"clone: public HTTPS WAV/MP3/OGG/FLAC/M4A, at most 10 MiB; imported privately. Every redirect is validated."},"video_url":{"type":"string","format":"uri","description":"Video-to-audio models take a public HTTPS MP4; actual file duration is used."},"consent":{"type":"boolean","description":"clone requires true: permission to use the reference voice. Market and site input switches still apply."},"text":{"type":"string","maxLength":10000,"description":"what to say (tts or clone)"},"prompt":{"type":"string","maxLength":1500,"description":"what music or sound to make"},"voice":{"type":"string"},"lang":{"type":"string","enum":["ko","ja","zh","en"]},"seconds":{"type":"number"},"lyrics":{"type":"string","maxLength":3000},"instrumental":{"type":"boolean"},"speed":{"type":"number","minimum":0.5,"maximum":2},"seed":{"type":"integer","minimum":0}},"allOf":[{"if":{"anyOf":[{"properties":{"mode":{"const":"clone"}},"required":["mode"]},{"required":["audio_url"]}]},"then":{"required":["text","audio_url","consent"],"properties":{"consent":{"const":true},"mode":{"const":"clone"}}}},{"if":{"properties":{"model":{"enum":["kling-v2a","thinksound"]}},"required":["model"]},"then":{"required":["video_url"],"properties":{"mode":{"const":"sfx"}}}}]},"Character":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"refs":{"type":"array","items":{"type":"string","format":"uri"}},"createdAt":{"type":"integer"}}},"AppList":{"type":"object","properties":{"apps":{"type":"array","items":{"type":"object","additionalProperties":true}},"video_apps":{"type":"array","items":{"type":"object","additionalProperties":true}},"notes":{"type":"string"}}},"Job":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["queued","running","done","failed","canceled"]},"model":{"type":"string"},"mode":{"type":"string"},"type":{"type":"string"},"credits":{"type":"integer"},"created_at":{"type":"integer"},"finished_at":{"type":["integer","null"]},"results":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"kind":{"type":"string"},"width":{"type":"integer"},"height":{"type":"integer"},"seed":{"type":"integer"}}}},"error":{"type":"string"}}}}}}