POST /v1/chat/completions

A thin translation layer so an existing OpenAI SDK can talk to Revoye by changing one base URL. It has no logic of its own: it translates the request in, queues it exactly as /v1/completions does, waits for the response the same way wait: true does, and translates the answer out.

{
  "model": "revoye/auto",
  "messages": [
    { "role": "system", "content": "You write short, friendly product copy." },
    { "role": "user", "content": "Describe a handmade ceramic mug in two sentences." }
  ],
  "stream": false
}

Model names

The ids are the same vocabulary provider uses on the native endpoint. An id Revoye does not recognise is a 400 INVALID_REQUEST.

Four things behave differently

Documented rather than hidden, because each of them would otherwise look like a bug.

1 · The call waits for the response, for up to 10 minutes. A finished request returns 200 in the standard shape, with the response in choices[0].message.content:

{
  "id": "job_01JAY7Q2K8XYZ",
  "object": "chat.completion",
  "created": 1760346842,
  "model": "revoye/auto",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Shaped by hand and glazed in small batches…" },
      "finish_reason": "stop"
    }
  ],
  "usage": null,
  "_revoye": { "job_id": "job_01JAY7Q2K8XYZ", "status": "succeeded" }
}

A request still running after 10 minutes returns 504 JOB_TIMEOUT with its id in details.job_id; it keeps running, and the response can be collected from GET /v1/completions/{id}. A failed or cancelled request returns the same error envelope as the native endpoint. Send revoye_wait: false to have the call return 202 at once instead, with the job id and message.content set to null.

2 · messages are flattened into one request. system messages come first, and the other turns follow as context, each labelled User: or Assistant:. This is not a stateful conversation API. To follow up on an earlier response, use the native endpoint with conversation_ref and mode: "continue".

Because they become one request, they share one request's limits: at most 256 messages, each at most 100 000 characters, and the flattened result at most 100 000 characters. Over any of those is a 400 INVALID_REQUEST, or a 413 PAYLOAD_TOO_LARGE for the flattened total — the same ceiling prompt has on the native endpoint, measured on the same text.

3 · stream: true returns 400. Revoye returns complete responses. Silently ignoring the flag would look like a hang, which is worse than an error.

4 · usage is null. This endpoint does not report token counts. Your token use is counted against your plan and shown in the dashboard and in quota on GET /v1/status. If your code does arithmetic on usage, guard it.

Choosing Desk or Cloud

An OpenAI client has no field for it, so there are two ways: revoye_channel in the body (auto, desk or cloud — most SDKs pass unknown fields through as extra_body), or a Revoye-Channel header, which every SDK can set as a default header. The body field wins when both are present. Omitted, it is auto. The rules are those of channel on /v1/completions.

Idempotency-Key works here exactly as on the native endpoint.

When to use the native endpoint instead

The compatibility layer exists so an OpenAI SDK works unchanged. Everything Revoye-specific is on /v1/completions: callback_url, timeout_ms, deadline_ms, priority, metadata, and conversation continuation.

Errors

Same envelope and same codes as /v1/completions, plus INVALID_REQUEST for stream: true and for an unrecognised model. Requires completions:write.