{"openapi":"3.1.0","info":{"title":"Creovox AI API","version":"1.0.0","description":"Asynchronous generation API. Create a task, then poll GET /api/v1/tasks/{task_id} until status is succeeded or failed. Requests spend paid credits only; failed tasks are refunded automatically."},"servers":[{"url":"https://creovox.ai"}],"security":[{"bearerAuth":[]}],"paths":{"/api/v1/models":{"get":{"summary":"List models (no key needed)","operationId":"listModels","security":[],"responses":{"200":{"description":"Models"}}}},"/api/v1/models/{model_id}":{"get":{"summary":"Get a model with its input schema and pricing (no key needed)","operationId":"getModel","security":[],"parameters":[{"name":"model_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Model"},"404":{"description":"Unknown model (not_found)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/tasks":{"post":{"summary":"Create a generation task","operationId":"createTask","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,128}$"},"description":"Recommended. Retrying with the same key returns the same task and never charges twice. Reusing a key for a different request returns 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","additionalProperties":false,"required":["model","input"],"properties":{"model":{"type":"string","const":"gpt-image-2.6"},"input":{"type":"object","additionalProperties":false,"required":["prompt"],"properties":{"prompt":{"type":"string","minLength":1,"maxLength":20000},"variant":{"type":"string","enum":["flare","sunburst","economy"],"default":"flare"},"aspect_ratio":{"type":"string","enum":["auto","1:1","3:2","2:3","4:3","3:4","5:4","4:5","16:9","9:16","2:1","1:2","21:9","9:21","3:1","1:3"],"default":"auto","description":"economy accepts only: auto, 1:1, 16:9, 9:16, 3:2, 2:3, 21:9, 4:3"},"resolution":{"type":"string","enum":["1k","2k","4k"],"default":"1k","description":"economy always renders 1k"},"output_format":{"type":"string","enum":["png","jpeg","webp","gif"],"default":"png","description":"GIF is opt-in and supports text-to-image only"},"gif_preset":{"type":"string","enum":["gif-short","gif-smooth","gif-hd"],"description":"Required when output_format is gif"},"expected_credits":{"type":"integer","minimum":1,"description":"Required for GIF; checked against the server price and never used as the charge amount"},"images":{"type":"array","maxItems":16,"items":{"type":"string","format":"uri"},"description":"Public HTTP(S) reference image URLs. Present → image-to-image edit."}}}}}]}}}},"responses":{"200":{"description":"Task","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/Task"}}}]}}}},"400":{"description":"Invalid request (invalid_request)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, disabled or deleted API key (invalid_api_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough paid credits (insufficient_credits)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key belongs to another site (key_not_allowed) or the account is suspended (account_suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency-Key reused for a different request (idempotency_conflict)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body larger than 64 KB (payload_too_large)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Content-Type must be application/json (unsupported_media_type)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or concurrency limit reached; see Retry-After (rate_limited)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The provider could not start the task (provider_error; data.task_id is refunded automatically) or the service failed (upstream_unavailable)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Awaiting debit confirmation (billing_unconfirmed) or provider acceptance (submission_unconfirmed). Keep data.task_id and poll it. The service may also be unavailable (upstream_unavailable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List tasks created with this API key","operationId":"listTasks","parameters":[{"name":"model","in":"query","schema":{"type":"string"},"description":"Required when the site exposes more than one model."},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Tasks, newest first"},"400":{"description":"Invalid query (invalid_request)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, disabled or deleted API key (invalid_api_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key belongs to another site (key_not_allowed) or the account is suspended (account_suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; see Retry-After (rate_limited)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Upstream service unavailable (upstream_unavailable)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/tasks/{task_id}":{"get":{"summary":"Get task status and output","operationId":"getTask","parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Task","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"properties":{"data":{"$ref":"#/components/schemas/Task"}}}]}}}},"401":{"description":"Missing, invalid, disabled or deleted API key (invalid_api_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key belongs to another site (key_not_allowed) or the account is suspended (account_suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Task not found for this API key (not_found)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; see Retry-After (rate_limited)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Upstream service unavailable (upstream_unavailable)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/account/credits":{"get":{"summary":"Credit balance of the key owner","operationId":"getCredits","responses":{"200":{"description":"Balance; the API spends paid_credits only"},"401":{"description":"Missing, invalid, disabled or deleted API key (invalid_api_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key belongs to another site (key_not_allowed) or the account is suspended (account_suspended)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests for this key; see Retry-After (rate_limited)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Upstream service unavailable (upstream_unavailable)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key from your dashboard (API Keys)."}},"schemas":{"Envelope":{"type":"object","required":["code","message","data"],"properties":{"code":{"type":"integer","const":200},"message":{"type":"string"},"data":{}}},"Error":{"type":"object","required":["code","message","error_type"],"properties":{"code":{"type":"integer","description":"Same as the HTTP status"},"message":{"type":"string"},"error_type":{"type":"string","enum":["invalid_request","invalid_api_key","insufficient_credits","key_not_allowed","account_suspended","not_found","method_not_allowed","unsupported_media_type","payload_too_large","idempotency_conflict","expected_credits_mismatch","gif_disabled","billing_identity_changed","rate_limited","billing_unconfirmed","submission_unconfirmed","provider_error","upstream_unavailable","internal_error"]},"data":{"type":["object","null"]}}},"Task":{"type":"object","required":["task_id","model","status","output","credits_charged","refund_pending","error","created_at"],"properties":{"task_id":{"type":"string"},"model":{"type":"string"},"status":{"type":"string","enum":["processing","succeeded","failed"],"description":"succeeded and failed are final."},"output":{"type":["object","null"],"properties":{"images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"}}}}}},"credits_charged":{"type":"integer","description":"Confirmed credits charged, net of completed refunds. An unconfirmed debit may not yet be reflected."},"refund_pending":{"type":"boolean","description":"True while the refund of a failed task is still being applied. It completes on its own; no further polling is needed."},"error":{"type":["object","null"],"properties":{"message":{"type":"string"}}},"created_at":{"type":["string","null"],"format":"date-time"}}}}}}