REST API

Call SocAIty models directly over HTTP when you cannot use the SDK. We recommend the Python SDK for most integrations because it handles polling, file uploads, and retries for you. Reach for the REST API from languages we do not yet ship a client for, from edge runtimes, or from shell scripts.

Reference under construction

Per-model paths shown below are illustrative. The canonical path for any service is the one the SDK sends to, plus the URLs SocAIty stamps onto every job response (refresh_job_url, cancel_job_url). The full OpenAPI spec lands with the public catalog.

Streaming is alpha. STREAMING is part of the canonical job-state enum and SocAIty returns a text/event-stream response for streaming workers, but client-side streaming consumption is still being rolled out per model. Treat streaming as model-specific until each service flags it as stable.

Base URL and authentication

The inference base URL is https://api.socaity.ai/v1/. Every request carries Authorization: Bearer <SOCAITY_API_KEY>. Override the base via the SOCAITY_INFER_BACKEND_URL environment variable if you are running against a staging cluster.

# Replace {service} with the path the SDK uses for your model
curl -X POST https://api.socaity.ai/v1/{service} \
  -H "Authorization: Bearer $SOCAITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "hello world"}'

Endpoint types

Each service exposes one or more paths. Fast services return the inference result directly; GPU-heavy services return a job handle you poll.

SYNC

Synchronous

Returns the inference result directly in the response body. Use for fast services where the worker finishes in a few seconds. The connection blocks until the worker is done.

ASYNC

Asynchronous

Returns a job envelope immediately with id, status, and refresh_job_url. Poll the refresh URL until status reaches a terminal state. Use for GPU-heavy services and anything that runs longer than a typical HTTP timeout.

Job lifecycle

Async services return a job handle immediately with id, status, and a refresh_job_url. Poll that URL until status reaches one of the terminal states: FINISHED, FAILED, TIMEOUT, or CANCELLED. The Python SDK polls every second by default.

PENDING: submitted, not yet assigned

QUEUED: waiting in the provider queue

PROCESSING: running on a worker

STREAMING: emitting an SSE stream (alpha)

FINISHED: terminal, result is set

FAILED: terminal, see error field

TIMEOUT: terminal, server-side timeout

CANCELLED: terminal, cancelled by client

UNKNOWN: provider status did not map

# Submit the inference request
POST https://api.socaity.ai/v1/{service}
→ 200  {
    "id": "job_abc123",
    "status": "QUEUED",
    "progress": 0,
    "refresh_job_url": "https://api.socaity.ai/v1/jobs/job_abc123",
    "cancel_job_url":  "https://api.socaity.ai/v1/jobs/job_abc123/cancel"
  }

# Poll the URL SocAIty handed you (do not hard-code the path)
GET  {refresh_job_url}
→ 200  { "status": "PROCESSING", "progress": 0.45 }
→ 200  { "status": "FINISHED", "result": "..." }

# Cancel a running job by POSTing to the cancel URL
POST {cancel_job_url}
→ 200  { "status": "CANCELLED" }

Job response schema

Every async response follows the same envelope. Provider-specific fields (RunPod adds delayTime and executionTime; Replicate adds metrics and execution_time_ms) layer on top of the base shape below.

Field	Type	Description
`id`	`string`	Stable identifier for the job. Use it to look up the job later if you lose the refresh URL.
`status`	`APIJobStatus`	One of PENDING, QUEUED, PROCESSING, STREAMING, FINISHED, FAILED, TIMEOUT, CANCELLED, UNKNOWN.
`progress`	`float \| null`	Completion fraction between 0.0 and 1.0. Null until the worker reports progress.
`result`	`any \| null`	Inference output. Populated once status is FINISHED. Shape depends on the model.
`error`	`string \| null`	Error message. Populated once status is FAILED.
`refresh_job_url`	`string \| null`	URL to GET for the latest job state. SocAIty stamps this on every async response.
`cancel_job_url`	`string \| null`	URL to POST to cancel the job. Present whenever cancellation is supported.
`service_specification`	`object \| null`	Catalog metadata about the service that produced this job (id, version, hardware profile).

Error responses

Worker capacity in the active region bounds throughput. Transient 503 responses surface under provider overload and are safe to retry.

HTTP status	Meaning	Action
401	Unauthorized	Missing or malformed API key. Check the Authorization header.
403	Forbidden	Valid key, but not entitled to this service. Confirm your plan or service permissions.
404	Not found	Wrong URL or the API key is not allowed to see the service. Verify both.
500	Server error	Treat as transient. Retry once with a short delay, then escalate to support if it persists.
503	Service unavailable	Provider capacity briefly saturated. Retry after a short backoff.

Next steps

Python SDK. Skip manual polling and file plumbing for any project that can ship a Python dependency.
JavaScript SDK. The browser and Node equivalent for the same job model described above.
Secrets. Create, rotate, and scope the key you send in the Authorization header.
Billing. How GPU-seconds in PROCESSING turn into your invoice, and what queued time costs you (nothing).

Billing & Credits