REST API

Low-level HTTP API reference. For most use cases, the Python or JS SDK is recommended.

API Reference Under Construction

Endpoint URLs shown below are illustrative. Use the SDK for verified endpoints until the full OpenAPI spec is published.

Coming soon: end-to-end streaming and status updates. STREAMING appears in the canonical job-state enum, but the streaming transport is still being rolled out per model. Until then, treat any streaming behaviour as model-specific and check each service's docs.

Base URL & Authentication

All requests must include a Authorization: Bearer <key> header.

curl -X POST https://api.socaity.ai/v1/{model}/generate \
  -H "Authorization: Bearer $SOCAITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "hello world"}'

Endpoint Types

SYNC

Synchronous

Returns the result directly in the response body. Best for fast operations (< 5s). Blocks until complete.

ASYNC

Asynchronous

Returns a job_id immediately. The client polls GET /v1/jobs/{id} until FINISHED. Best for GPU-heavy tasks.

Job Lifecycle

Async endpoints return a job_id immediately. Poll the job status endpoint until status is FINISHED.

PENDING — submitted, waiting for a worker

QUEUED — in the provider queue

PROCESSING — running on a worker

STREAMING — producing output incrementally over SSE

FINISHED — complete, result available

FAILED — check error field

TIMEOUT — server-side timeout exceeded

CANCELLED — cancelled by client

UNKNOWN — fallback when status did not map

# Submit async job
POST /v1/{model}/generate
→ 202  { "job_id": "job_abc123", "status": "PENDING" }

# Poll for result
GET /v1/jobs/job_abc123
→ 200  { "status": "PROCESSING", "progress": 0.45 }
→ 200  { "status": "FINISHED", "result": "..." }

# Cancel a job
DELETE /v1/jobs/job_abc123
→ 200  { "status": "CANCELLED" }

Job Response Schema

Field	Type	Description
`job_id`	`string`	Unique identifier for the remote job.
`status`	`APIJobStatus`	PENDING \| QUEUED \| PROCESSING \| STREAMING \| FINISHED \| FAILED \| TIMEOUT \| CANCELLED \| UNKNOWN
`progress`	`float \| null`	Completion 0.0→1.0. Null if not reported.
`result`	`any \| null`	Inference output when status is FINISHED.
`error`	`string \| null`	Error message when status is FAILED.
`refresh_job_url`	`string \| null`	Poll URL for the latest job status.
`cancel_job_url`	`string \| null`	URL to request cancellation.

Error Codes

HTTP Status	Meaning	Action
401	Unauthorized	Check API key and Authorization header.
403	Forbidden	Key lacks required permission.
422	Validation Error	Check request body against the model schema.
429	Rate Limited	Back off and retry with exponential delay.
500	Server Error	Retry once. If persists, contact support.
503	Service Unavailable	Cold start or capacity issue — retry in 30s.

Billing & Credits