Providers · Reference

Transport declarations

Every field of the openai-compatible, sync-rest and submit-poll declarations, with a complete example of each.

A transport tells Sushibelt how to call your API: where, with which key header, and where the result is in the answer. It belongs to one of 3 families — `openai-compatible`, `sync-rest`, `submit-poll` — and each family accepts exactly the fields below. A field a family does not know is refused by name, so a typo is caught when you declare, not when a customer runs your model.

No field is a template: there are no placeholders such as {taskId}. Sushibelt joins paths in fixed ways, given with each field. What each family sends and expects is explained in run your own endpoint.

Rules every family shares#

Shared fields
Field	Description
`baseUrl`string · Required	An absolute `http` or `https` URL with no trailing slash, such as `https://api.example.com/v1`. For a claim it must be on your verified domain or one of its subdomains.
`family`string · Optional	Optional: `openai-compatible`, `sync-rest`, `submit-poll`. Sushibelt adds it to a transport it stores; you may send it back. When a claim is declared it is dropped and your provider's own family is used.

openai-compatible#

One field. The rest is fixed by the family: POST {baseUrl}/chat/completions, with Authorization: Bearer and your key.

openai-compatible fields
Field	Description
`baseUrl`string · Required	Everything before `/chat/completions`, with no trailing slash.

openai-compatible transportJSON

{
  "baseUrl": "https://api.example.com/v1"
}

sync-rest#

sync-rest fields
Field	Description
`baseUrl`string · Required	The origin requests go to. Each model's request goes to the endpoint its descriptor names, which must be on this origin.
`method`string · Required	One of `GET`, `POST`. Declare `POST`: the request carries a JSON body, and a transport declaring `GET` fails its probe.
`auth`object · Required	How the key is sent. See auth below.
`delivery`object · Required	`transport` must be `sync`. See delivery below.

sync-rest transport — a link in the answerJSON

{
  "baseUrl": "https://api.example.com",
  "method": "POST",
  "auth": {
    "scheme": "bearer"
  },
  "delivery": {
    "transport": "sync",
    "produces": "images",
    "result": {
      "kind": "url",
      "path": "data.0.url"
    }
  }
}

sync-rest transport — base64 in the answer, key in a named headerJSON

{
  "baseUrl": "https://api.example.com",
  "method": "POST",
  "auth": {
    "scheme": "header",
    "header": "x-api-key"
  },
  "delivery": {
    "transport": "sync",
    "produces": "images",
    "result": {
      "kind": "base64",
      "path": "data.0.b64_json",
      "mime": "image/png"
    }
  }
}

sync-rest transport — the answer is the fileJSON

{
  "baseUrl": "https://api.example.com",
  "method": "POST",
  "auth": {
    "scheme": "header",
    "header": "x-api-key"
  },
  "delivery": {
    "transport": "sync",
    "produces": "audio",
    "result": {
      "kind": "bytes",
      "mime": "audio/mpeg"
    }
  }
}

submit-poll#

submit-poll fields
Field	Description
`baseUrl`string · Required	The origin requests go to. Each model's submit request goes to the endpoint its descriptor names, which must be on this origin.
`method`string · Required	One of `GET`, `POST`. Declare `POST`: the submit request carries a JSON body, and a transport declaring `GET` fails its probe.
`pollPath`string · Required	Starts with `/`, no trailing slash. Sushibelt asks for a task at `baseUrl + pollPath + "/" + taskId`. This is a URL path, not the status field — that is `delivery.poll.statusPath`.
`auth`object · Required	How the key is sent, on the submit and on every poll. See auth below.
`delivery`object · Required	`transport` must be `poll`, with a `poll` block. See delivery below.
`taskIdPath`string · Optional	A dotted path to the task id in the submit answer, such as `data.task_id` — letters, digits and underscores between dots. Without it, Sushibelt tries `id`, `task_id`, `data.id`, `data.task_id`, `result.id`, `result.task_id`, in order.

submit-poll transportJSON

{
  "baseUrl": "https://api.example.com",
  "method": "POST",
  "pollPath": "/v2/task",
  "auth": {
    "scheme": "bearer"
  },
  "taskIdPath": "data.task_id",
  "delivery": {
    "transport": "poll",
    "produces": "model_mesh",
    "result": {
      "kind": "url",
      "path": [
        "data.output.model",
        "data.output.pbr_model"
      ]
    },
    "poll": {
      "statusPath": "data.status",
      "success": [
        "success"
      ],
      "failure": [
        "failed",
        "cancelled",
        "expired"
      ],
      "errorPath": "data.message"
    }
  }
}

auth#

auth fields
Field	Description
`scheme`string · Required	One of `bearer`, `header`. `bearer` sends `Authorization: Bearer KEY`; `header` sends the key, as it is, in the header you name.
`header`string · Optional	Required for `header`, and refused for `bearer`. The header name, such as `x-api-key`.

auth — bearerJSON

{
  "scheme": "bearer"
}

auth — a named headerJSON

{
  "scheme": "header",
  "header": "x-api-key"
}

delivery#

delivery fields
Field	Description
`transport`string · Required	One of `sync`, `poll`, `webhook`; in a transport it must match the family — `sync` for sync-rest, `poll` for submit-poll.
`produces`string · Required	What the output is: `images`, `model_mesh`, `audio`. `text` is refused — a delivery describes a file.
`result`object · Required	Where the output is. See result below.
`poll`object · Optional	Required when `transport` is `poll`, and refused otherwise. See poll below.

result#

result fields
Field	Description
`kind`string · Required	One of `url`, `base64`, `bytes`. `url`: a link to the file. `base64`: the file as base64 text. `bytes`: the answer body is the file — not allowed with `poll`. For submit-poll, declare `url`.
`path`string or string[] · Optional	Required for `url` and `base64`, refused for `bytes`. A dotted path into the JSON answer (`data.0.url`), or a list of paths tried in order; the first that holds text is used.
`mime`string · Optional	Required for `base64` and `bytes`: the file's type, such as `image/png`.

poll#

poll fields
Field	Description
`statusPath`string · Required	A dotted path to the task's status in the poll answer; `""` for the whole answer. A status that is not text is compared as its JSON text.
`success`string[] · Required	At least one status meaning "done — read the result".
`failure`string[] · Required	At least one status meaning "failed for good". Without one, a failed task would be polled until the step times out. A status cannot be in both lists.
`errorPath`string · Optional	A dotted path to a readable failure message, shown when the task fails.

Tip: check before you declare

Point each path at a real answer from your API. The probe reads your paths from a real call, and a path that names a field your answer does not have fails it: no value at declared output path ….

Refusals#

A declaration that breaks a rule is refused with 400 Invalid transport declaration and a problems list, one line per broken rule. The lines are listed in the probe reference.

Unknown field: unknown field "…" — a sync-rest transport only carries baseUrl, method, auth, delivery.
For a claim, an endpoint off your domain: baseUrl: must be on example.com or one of its subdomains.