AI Platform Integration Guide (English)

Protocol

API version: v1
Content type: application/json
Every request carries X-Client-App: <assigned application code>.
Clients should generate X-Request-Id.
Treat every ID as a string and every timestamp as UTC ISO 8601.
Branch on stable error.code; do not parse human-readable messages.

Atlas token exchange

POST /api/v1/auth/exchange/atlas
X-Client-App: heyphoto

{
  "realm": "intl",
  "atlas_token": "<Atlas login token>",
  "device_id": "<installation ID>"
}

The platform validates the token against the configured Atlas binding, maps the verified Atlas userid to an internal user, then returns a short-lived platform access token and a rotating refresh token. The Atlas token is never persisted.

Refresh and revoke:

POST /api/v1/auth/refresh
POST /api/v1/auth/revoke

Discover workflows

GET /api/v1/workflows
X-Client-App: heyphoto

The response includes the workflow code, immutable version, localized metadata, authentication mode, and JSON input/output schemas.

Submit an asynchronous job

POST /api/v1/jobs
X-Client-App: heyphoto
Authorization: Bearer <platform access token>
Idempotency-Key: <stable UUID for this user action>

{
  "workflow_code": "image.enhance",
  "workflow_version": 1,
  "input": {"asset_id": "...", "strength": 0.8}
}

The API immediately returns HTTP 202. A network retry must reuse the same idempotency key and identical body. The same key with a different body returns IDEMPOTENCY_CONFLICT.

Poll GET /api/v1/jobs/{job_id} with backoff. The initial states are accepted, queued, running, waiting_external, cancel_requested, succeeded, failed, cancelled, and expired. Request cancellation with POST /api/v1/jobs/{job_id}/cancel.

Anonymous workflows (auth_mode=optional/none) require a stable per-installation X-Anonymous-Id. This is not an identity credential and never grants private history or cross-device access.

Error envelope

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "request rate limit exceeded",
    "request_id": "...",
    "details": {"retry_after_seconds": 30}
  }
}

Core codes: CLIENT_APP_UNKNOWN, AUTH_REQUIRED, AUTH_INVALID_TOKEN, AUTH_UPSTREAM_REJECTED, AUTH_UPSTREAM_REQUEST_INVALID, AUTH_UPSTREAM_UNAVAILABLE, WORKFLOW_NOT_FOUND, IDEMPOTENCY_CONFLICT, JOB_NOT_FOUND, JOB_NOT_CANCELLABLE, RATE_LIMITED, and INTERNAL_ERROR.