UPDATED 2026.05.11READ 20 MINSUGGEST AN EDIT →

CH·04API

Endpoint reference.

Every /v1 endpoint. Base URL: https://api.demo.deeprelay.ai/v1. Cross-cutting behaviors (auth, errors, pagination, idempotency, rate limits) live in Conventions.

§ 04.1Serverless inference¶

OpenAI-compatible inference: chat, embeddings, image and video. Point any OpenAI client at https://api.deeprelay.ai/v1 and pass your key as the bearer token. Scope: serverless: read for the catalog, serverless: write to run inference.

GET/v1/modelsSCOPE · serverless: read

List every served model. Ids are canonical deeprelay/<slug> names.

Query parameters

modalitystring

Filter by surface: chat, image, video or embedding.

curl "https://api.demo.deeprelay.ai/v1/models?modality=chat" \
  -H "Authorization: Bearer deeprelay_live_..."

200 OK

{
  "object": "list",
  "data": [
    {
      "id":       "deeprelay/qwen2.5-7b-instruct",
      "object":   "model",
      "owned_by": "deeprelay"
    }
  ]
}

GET/v1/models/{id}SCOPE · serverless: read

Fetch one model by id. A model id that exists but is not served on the requested surface returns 404 model_not_found.

POST/v1/chat/completionsSCOPE · serverless: write

Create a chat completion. Set stream: true for a Server-Sent Events stream terminated by data: [DONE].

Request body

modelstringrequired

Canonical model id, e.g. deeprelay/qwen2.5-7b-instruct.

messagesarrayrequired

OpenAI-shaped message list.

streamboolean

Stream the response as SSE chunks. Defaults to false.

max_tokensinteger

Upper bound on completion tokens.

curl https://api.demo.deeprelay.ai/v1/chat/completions \
  -H "Authorization: Bearer deeprelay_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deeprelay/qwen2.5-7b-instruct",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

200 OK

{
  "id":      "chatcmpl-...",
  "object":  "chat.completion",
  "model":   "deeprelay/qwen2.5-7b-instruct",
  "choices": [
    {
      "index":         0,
      "message":       {"role": "assistant", "content": "Hello!"},
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens":     9,
    "completion_tokens": 3,
    "total_tokens":      12
  }
}

POST/v1/embeddingsSCOPE · serverless: write

Synchronous embeddings. Accepts a single string or an array of up to 2048 strings and returns one float vector per input, in request order. encoding_format accepts only float. Billed on prompt tokens, so usage carries no completion tokens.

POST/v1/images/generationsSCOPE · serverless: write

Generate images, billed per image. Pass an Idempotency-Key so a retried request replays the original response without a second charge.

POST/v1/videosSCOPE · serverless: write

Submit an asynchronous text-to-video job. Returns a job with status queued; poll GET /v1/videos/{id} until completed, then stream the result from GET /v1/videos/{id}/content. Subscribe to webhooks to be told instead of polling.

§ 04.2Webhook endpoints¶

Register URLs that receive signed event deliveries. The signing secret is returned once, at creation, and by no later read. Scope: webhooks: read for reads, webhooks: write for writes. See Webhooks for the delivery format and signature verification.

GET/v1/webhook-endpointsSCOPE · webhooks: read

List your endpoints with their subscribed event types. Paginated. Secrets are never included in a listing.

curl https://api.demo.deeprelay.ai/v1/webhook-endpoints \
  -H "Authorization: Bearer deeprelay_live_..."

POST/v1/webhook-endpointsSCOPE · webhooks: write

Request body

urlstringrequired

HTTPS URL that receives the deliveries.

event_typesarrayrequired

Explicit list, e.g. ["video.completed", "video.failed"]. There is no all shortcut.

DELETE/v1/webhook-endpoints/{id}SCOPE · webhooks: write

Stop deliveries to an endpoint. Its signing secret goes with it.

§ 04.3Operations¶

Async writes return an Operation pointer that you poll until it reaches a terminal state.

State	Meaning
`pending`	Accepted, not yet started. Initial state.
`in_progress`	Worker is actively executing. `resource_id` may now be populated.
`succeeded`	Terminal. The resource is in its target state.
`failed`	Terminal. See `error` for detail.
`cancelled`	Terminal. Caller aborted (rare in v1).

GET/v1/operations/{id}

Fetch an operation by its UUID. Operations are scoped to the API key that created them: cross-key access returns 404 not_found.

Suggested polling: backoff 1s → 2s → 4s → 8s → 16s → 30s.

curl https://api.demo.deeprelay.ai/v1/operations/5f1b8a9c-... \
  -H "Authorization: Bearer deeprelay_live_..."

200 OK · in progress

{
  "operation_id": "5f1b8a9c-...",
  "state":        "in_progress",
  "resource_id":  "res_01HX...",
  "created_at":   "2026-05-08T17:00:00Z",
  "updated_at":   "2026-05-08T17:00:35Z",
  "completed_at": null
}

200 OK · succeeded

{
  "operation_id": "5f1b8a9c-...",
  "state":        "succeeded",
  "resource_id":  "res_01HX...",
  "completed_at": "2026-05-08T17:01:30Z",
  ...
}

200 OK · failed

{
  "operation_id": "5f1b8a9c-...",
  "state":        "failed",
  "error": {
    "code":   "operation_failed",
    "detail": "The operation could not be completed"
  },
  ...
}

§ 04.4Usage¶

Time-bucketed usage and cost. Scope: billing: read. Defaults to a 30-day window when start/end are omitted.

GET/v1/usageSCOPE · billing: read

Query parameters

bucketstring

One of hour, day, week, month. Default depends on window length.

startISO 8601

Inclusive lower bound.

endISO 8601

Exclusive upper bound.

cursor / limitstandard

See pagination conventions.

curl "https://api.demo.deeprelay.ai/v1/usage?bucket=day" \
  -H "Authorization: Bearer deeprelay_live_..."

200 OK

{
  "data": [
    {
      "bucket_start": "2026-05-07T00:00:00Z",
      "cost_cents":   7176
    },
    {
      "bucket_start": "2026-05-08T00:00:00Z",
      "cost_cents":   3588
    }
  ],
  "next_cursor": null
}