# Aixio media API
Authentication: Authorization: Bearer <Aixio REST API key>. Keep keys server-side.
HTTP contract: /api/openapi.json
1. GET /v1/models; choose an available model and its documented inputs.
2. POST /v1/generations with kind, model_id, params, and a stable Idempotency-Key.
3. HTTP202 is acceptance, not a finished result. Persist id and status_url.
4. GET status_url with the same bearer every poll_after_seconds (default3).
5. queued/running: wait. succeeded: use output.assets, output.text or output.layers. failed/cancelled: stop.
6. result_url is the same job resource. Signed private URLs expire; GET again to refresh.
7. POST cancel_url requests cancellation; disconnecting does not cancel a job.
8. Lost POST response: retry identical input with the same Idempotency-Key.
9. Different input under an existing idempotency key returns409. Never silently start a new paid job.
10. HTTP429/503: back off using Retry-After. HTTP401: invalid/expired/revoked key. HTTP402: insufficient wallet or key budget.
TypeScript: submit(input,idempotencyKey), wait(id), generation(id), cancel(id).
Convenience subscribe(input,idempotencyKey) performs durable submit followed by polling.
Supported: available direct image/video/audio/text models, layer-v1 and utility operations in the catalog.
Private input: POST /v1/uploads with content_type; PUT bytes to upload_url; submit source_url.
Layer-v1: kind=image, image_url=owned source_url, output_width/output_height=coordinate dimensions.
Layers: ordered image/text visuals with geometry, fonts and decomposition counts.
Text: params.prompt only; stateless, token-estimated then usage-settled; output.text.
Unsupported: agent workspace endpoints, customer webhooks and WebSockets.
All calls are short HTTP requests. Synchronous executors still have host/provider timeouts; failures are terminal, not implicit retries.

Customer-facing reference examples with equivalent routes grouped by model name, and per-mode parameter settings: /api/examples.json.
Runnable Node.js 18+ image-to-layers example: /api/examples/layer-v1.mjs.
Base URL: https://data.aixio.app/functions/v1/platform-api
Layer example body (replace image_url using the owned upload flow):
{"kind":"image","model_id":"aixio-layer-v1","params":{"image_url":"UPLOAD_SOURCE_URL","output_width":1024,"output_height":768}}
Upload: POST /v1/uploads {"content_type":"image/png"}; PUT the PNG bytes to upload_url with Content-Type: image/png and no bearer header; use source_url as image_url.
Run the layer script with AIXIO_API_KEY, AIXIO_REQUEST_ID, AIXIO_IMAGE_FILE pointing to a PNG. A new input/file needs a new request ID.
The script persists exact input and receipt (no API key) in a local state file. Keep it to retry a lost POST response with identical input and idempotency key, or resume polling without submitting another paid job.
Layer output: output.layers entries have kind=image|text, position={left,top,width,height,angle,flipX,flipY}, z_index, optional url/text/fonts, and layer data. Use position for output-space geometry. Signed resources expire; refresh GET.
output.decomposition={editable_layer_count,total_layer_count,fallback}. Counts vary. A successful fallback may be a flattened image, not editable objects. Do not infer editable success from status alone.
Text results: output.text. Media results: output.assets[].url. Layer results: output.layers. Failed/cancelled jobs are terminal with error or status, not successful empty assets.

## MCP and Designer for AI agents

- [MCP quickstart](https://aixio.app/mcp/): Exact hosted server URL, browser OAuth setup, client configuration and no-cost connection checks.
- [Designer guide](https://aixio.app/mcp/designer/): Brief → mockup → editable layers → implementation with design and design_status.
- [Agent skill](https://aixio.app/skills/aixio-designer/SKILL.md): Installable instructions for using the hosted Designer pipeline.

Hosted MCP URL: https://data.aixio.app/functions/v1/platform-api-mcp (Streamable HTTP; browser OAuth, not a REST key). Website sign-in alone does not authorize the connector. For Studio workspace work use ask_agent and agent_status; for a host-built design use design and design_status. Designer has two paid stages, mockup and layer extraction; design_status can start the extraction. Connection checks should only discover tools and read balance/list_workspaces. Keep design_id/request_id/target and resume existing jobs after timeouts. See the quickstart for host limitations and troubleshooting.