API reference

One connection for your tools.

Use an OpenAI-compatible client with your Luma Cloud key and the public Gateway URL.

New to the API?

Start with the quickstart or find your client guide.

Connection and authentication

Base URL: https://api.lumaos.cloud/v1
Authentication: Authorization: Bearer YOUR_API_KEY
Request body: Content-Type: application/json

Create a named key in API Wallet & keys. Use it from a server or trusted local client. Never expose it in a public website bundle.

Endpoints for API clients

Method	Path	Use
GET	`/models`	List model IDs available to your key.
POST	`/chat/completions`	Chat messages and compatible tool conversations.
POST	`/responses`	Clients that use the Responses protocol.
POST	`/responses/compact`	Compatible clients that need conversation compaction. Non-streaming only; do not send stream: true.

Paths are relative to the base URL. Models and capabilities describe how to select an ID and reasoning effort.

List models

Authenticated model list

curl --fail-with-body "https://api.lumaos.cloud/v1/models" \
  -H "Authorization: Bearer $LUMA_CLOUD_API_KEY"

Read each data[].id. Use the exact ID; refresh this list when a model is missing or access changes. The account shown in another app does not determine which models an API key can use.

Chat Completions

Send model and a messages array. Set stream: true to receive Server-Sent Events, or omit it to receive one JSON response. Non-streamed text is in choices[0].message.content; streamed text is in choices[].delta.content.

Chat Completions request

curl --fail-with-body -N "https://api.lumaos.cloud/v1/chat/completions" \
  -H "Authorization: Bearer $LUMA_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<JSON
{
  "model": "$LUMA_CLOUD_MODEL",
  "messages": [{"role": "user", "content": "Reply with hello."}],
  "stream": true
}
JSON

Responses

Send model and input over HTTP. Use SSE for streaming; WebSocket transport is not supported. With streaming, handle text delta events and the final completion or failure event. A returned response ID alone does not prove that the response finished.

Responses request

curl --fail-with-body -N "https://api.lumaos.cloud/v1/responses" \
  -H "Authorization: Bearer $LUMA_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<JSON
{
  "model": "$LUMA_CLOUD_MODEL",
  "input": "Reply with hello.",
  "stream": true
}
JSON

For continuing a conversation, follow the protocol supported by your client and include the required conversation context. Do not assume every OpenAI API endpoint or stored-response feature is available.

Reasoning and tool use

For Chat Completions, reasoning effort uses reasoning_effort. For Responses, use reasoning.effort. A model ID with an explicit effort suffix must agree with that field; a conflict returns reasoning_effort_conflict.

For tools, the client provides tool definitions, executes authorized calls and returns tool results. A response asking to call a tool is not the tool’s completed result. Test the client features you need with your chosen model.

Retries, timeouts and limits

On 429, honor Retry-After and reduce simultaneous requests. Do not treat every rate limit as an empty balance. A reasoning request can pause before text appears; use a suitable client timeout and a cancel control.

For an uncertain retry, reuse the same optional Idempotency-Key only for the same logical request and body. A 409 can mean the request is still running or that a result cannot be replayed; do not repeatedly create fresh requests to work around it. See error recovery.

For support, keep x-request-id or error.request_id, the HTTP status and the time. Remove keys and private prompt content from reports.

Billing and compatibility

Wallet keys share a prepaid API balance on any account. Builder keys use the Builder subscription allowance. Adding Wallet funds does not refill subscription quota. Review billing and API pricing.

These guides cover text and compatible tool workflows. OpenAI compatibility does not imply embeddings, image or video generation, realtime audio, hosted assistants, file storage or an Anthropic/Gemini endpoint. SuperGPT sign-in and desktop features have their own setup guide.

SDK examples →Client setup Troubleshooting