Technische Übersicht für Produkt- und Engineering-Teams.

Nutzen Sie diese Seite, um die Struktur der AIXpose REST API zu verstehen. Bei Kontakt besprechen wir API-Vereinbarung, Integrationsumfang, Authentifizierung, Limits und Produktionsanforderungen im Detail.

API-Zugang besprechen Beispiele ansehen

Architecture preview

REST resources, async jobs and webhook callbacks.

Create projects, upload source photos, request enhancements or videos, then receive status updates and CDN-ready outputs when processing completes.

1

Create a project for the property or listing.
2

Upload source photos and request one or more generated variants.
3

Poll status or subscribe to signed webhook events.
4

Approve the best picture version and optionally generate a short video.
5

Publish the project or sync CDN-ready media into your product.

Core concepts

The objects you will work with

These are the main concepts to plan against when designing a CRM, portal, automation workflow or media pipeline integration.

Organization

Your tenant for projects, credits, preferences, branding and API access.

Project

A listing, property or campaign that groups photos, generated assets and shared output defaults.

Picture

An original upload or generated derivative with status, public URL, version information and feedback.

Video

A short property reel generated from approved pictures, scene context and optional audio direction.

Instruction

The public generation recipe behind an enhancement: preset actions, custom prompts, quick actions or consistency goals.

Agent

An optional learning mode that can apply approved visual preferences automatically on future uploads.

Ressourcenkarte

Was über die API möglich ist

Diese Karte erklärt die Bausteine Ihrer Integration: Projekte bündeln Listing-Kontext, Bilder und Videos sind generierte Medien, Kataloge steuern UI-Optionen, Webhooks liefern Job-Updates und Credits helfen beim Nutzungsabgleich.

Projects

Create and manage listing-level workspaces for pictures, videos, defaults and review flows.

POST /v1/projects GET /v1/projects/{project_id} POST /v1/projects/{project_id}/publish

Pictures

Create pictures inside a project and request enhanced versions for staging, renovation, decluttering or exterior improvement.

POST /v1/projects/{project_id}/pictures POST /v1/pictures/{picture_id}/enhancements GET /v1/projects/{project_id}/pictures

Videos

Generate short listing reels from approved media, scene context and optional voice or background direction.

POST /v1/videos GET /v1/videos/{video_id} GET /v1/videos?project_id=...

Catalog

Populate your UI controls with supported models, output formats, scene types and action groups.

GET /v1/catalog/models GET /v1/catalog/actions GET /v1/catalog/aspect-ratios

Agent and quick actions

Use reusable prompts and learned preferences without exposing internal generation pipelines.

GET /v1/agent PATCH /v1/agent GET /v1/quick-actions

Credits and webhooks

Track consumption, reconcile generated assets and receive asynchronous status changes.

GET /v1/credits/balance GET /v1/credits/ledger Signed webhook events

Example snippets

Developer examples

These snippets show common integration patterns. Contact us to discuss your API agreement, integration details and production requirements.

Example 1

Create a project

Create a project for one listing, property or campaign.

JavaScript / fetch Preview

const project = await fetch('https://api.aixpose.art/v1/projects', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer aix_live_partner_key',
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({
    name: 'Gdynia apartment campaign',
    output: 'picture',
    picture_aspect_ratio: '16:9',
    picture_resolution: '2K'
  })
}).then((res) => res.json());

console.log(project.id);

Python / requests Preview

import requests
from uuid import uuid4

response = requests.post(
    "https://api.aixpose.art/v1/projects",
    json={
        "name": "Gdynia apartment campaign",
        "output": "picture",
        "picture_aspect_ratio": "16:9",
        "picture_resolution": "2K",
    },
    headers={
        "Authorization": "Bearer aix_live_partner_key",
        "Idempotency-Key": str(uuid4()),
    },
    timeout=30,
)

print(response.json()["id"])

Example 2

Upload an image from a URL

Use this when your image already exists in a CRM, DAM or storage bucket.

JavaScript / JSON URL Preview

const projectId = 'prj_123';

const picture = await fetch(
  `https://api.aixpose.art/v1/projects/${projectId}/pictures`,
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer aix_live_partner_key',
      'Content-Type': 'application/json',
      'Idempotency-Key': crypto.randomUUID()
    },
    body: JSON.stringify({
      source: {
        type: 'url',
        url: 'https://cdn.example.com/listings/4812/living-room.jpg'
      },
      scene_type: 'interior',
      scene_location: 'living_room',
      webhook_url: 'https://partner.example/aixpose/webhook'
    })
  }
).then((res) => res.json());

console.log(picture.id);

Python / JSON URL Preview

import requests
from uuid import uuid4

project_id = "prj_123"

response = requests.post(
    f"https://api.aixpose.art/v1/projects/{project_id}/pictures",
    json={
        "source": {
            "type": "url",
            "url": "https://cdn.example.com/listings/4812/living-room.jpg",
        },
        "scene_type": "interior",
        "scene_location": "living_room",
        "webhook_url": "https://partner.example/aixpose/webhook",
    },
    headers={
        "Authorization": "Bearer aix_live_partner_key",
        "Idempotency-Key": str(uuid4()),
    },
    timeout=30,
)

print(response.json()["id"])

Example 3

Upload an image as multipart form data

Use multipart when you send a raw file directly from a browser or backend.

JavaScript / FormData Preview

const projectId = 'prj_123';
const form = new FormData();

form.append('file', sourcePhoto);
form.append('scene_type', 'interior');
form.append('scene_location', 'living_room');
form.append('webhook_url', 'https://partner.example/aixpose/webhook');

const picture = await fetch(
  `https://api.aixpose.art/v1/projects/${projectId}/pictures`,
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer aix_live_partner_key',
      'Idempotency-Key': crypto.randomUUID()
    },
    body: form
  }
).then((res) => res.json());

console.log(picture.id);

Python / multipart Preview

import requests
from uuid import uuid4

project_id = "prj_123"

with open("living-room.jpg", "rb") as source_photo:
    response = requests.post(
        f"https://api.aixpose.art/v1/projects/{project_id}/pictures",
        data={
            "scene_type": "interior",
            "scene_location": "living_room",
            "webhook_url": "https://partner.example/aixpose/webhook",
        },
        files={"file": source_photo},
        headers={
            "Authorization": "Bearer aix_live_partner_key",
            "Idempotency-Key": str(uuid4()),
        },
        timeout=30,
    )

print(response.json()["id"])

Example 4

Upload an image as base64 JSON

Use base64 when your integration already holds the image bytes in memory.

JavaScript / base64 JSON Preview

import { readFile } from 'node:fs/promises';

const projectId = 'prj_123';
const image = await readFile('living-room.jpg');

const picture = await fetch(
  `https://api.aixpose.art/v1/projects/${projectId}/pictures`,
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer aix_live_partner_key',
      'Content-Type': 'application/json',
      'Idempotency-Key': crypto.randomUUID()
    },
    body: JSON.stringify({
      source: {
        type: 'base64',
        media_type: 'image/jpeg',
        data: image.toString('base64')
      },
      scene_type: 'interior',
      scene_location: 'living_room'
    })
  }
).then((res) => res.json());

console.log(picture.id);

Python / base64 JSON Preview

import base64
import requests
from uuid import uuid4

project_id = "prj_123"

with open("living-room.jpg", "rb") as image_file:
    image_base64 = base64.b64encode(image_file.read()).decode("utf-8")

response = requests.post(
    f"https://api.aixpose.art/v1/projects/{project_id}/pictures",
    json={
        "source": {
            "type": "base64",
            "media_type": "image/jpeg",
            "data": image_base64,
        },
        "scene_type": "interior",
        "scene_location": "living_room",
    },
    headers={
        "Authorization": "Bearer aix_live_partner_key",
        "Idempotency-Key": str(uuid4()),
    },
    timeout=30,
)

print(response.json()["id"])

Example 5

Enhance a picture

Send generation instructions to create one or more new variants.

JavaScript / fetch Preview

const pictureId = 'pic_source';

const enhancedPictures = await fetch(
  `https://api.aixpose.art/v1/pictures/${pictureId}/enhancements`,
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer aix_live_partner_key',
      'Content-Type': 'application/json',
      'Idempotency-Key': 'listing-4812-kitchen-v1'
    },
    body: JSON.stringify({
      instruction: {
        source: 'preset',
        actions: [
          'interior-style-japandi',
          'interior-decoration-medium'
        ]
      },
      variants: 2,
      aspect_ratio: '16:9',
      resolution: '2K',
      webhook_url: 'https://partner.example/aixpose/webhook'
    })
  }
).then((res) => res.json());

console.log(enhancedPictures);

Python / requests Preview

import requests

picture_id = "pic_source"

response = requests.post(
    f"https://api.aixpose.art/v1/pictures/{picture_id}/enhancements",
    json={
        "instruction": {
            "source": "preset",
            "actions": [
                "interior-style-japandi",
                "interior-decoration-medium",
            ],
        },
        "variants": 2,
        "aspect_ratio": "16:9",
        "resolution": "2K",
        "webhook_url": "https://partner.example/aixpose/webhook",
    },
    headers={
        "Authorization": "Bearer aix_live_partner_key",
        "Idempotency-Key": "listing-4812-kitchen-v1",
    },
    timeout=30,
)

print(response.json())

Example 6

Webhook event payload

Use webhook events to update your CRM, listing page or media queue when generation completes.

JSON / webhook body Preview

{
  "id": "evt_01HZY4Q6AV7M7K4QF9Q7S2A8E1",
  "type": "picture.completed",
  "created_at": "2026-05-06T05:56:00Z",
  "data": {
    "id": "pic_generated",
    "project_id": "prj_123",
    "status": "completed",
    "public_url": "https://cdn.aixpose.art/projects/prj_123/pic_generated.jpg",
    "version": 1,
    "subversion": 0,
    "scene_type": "interior",
    "scene_location": "living_room",
    "source_instruction": {
      "source": "preset",
      "actions": [
        "interior-style-japandi",
        "interior-decoration-medium"
      ]
    }
  }
}

Operational model

Built for asynchronous generation.

Picture and video generation runs asynchronously. Your integration should expect immediate acknowledgement, status transitions, signed webhook callbacks and idempotent writes for safe retries.

- Processing states for pictures and videos
- Signed events for completion and failure
- Version lineage for generated variants
- Credit balance and ledger reconciliation

Zugangsdetails

Lassen Sie uns API-Vereinbarung und Integrationsdetails besprechen.

Erzählen Sie uns, was Sie bauen möchten, welches Medienvolumen Sie erwarten und welche Systeme verbunden werden müssen. Gemeinsam prüfen wir kommerzielle Vereinbarung, Umfang und technische Details.

API-Integration besprechen

Next step

Bring AIXpose generation into your CRM, portal or real estate workflow.

Share your use case, expected media volume and integration goals. We will review the API agreement, integration details and technical requirements with you.

Discuss integration details Back to API overview