PLATFORM / API compatibility
API compatibility
Endpoint directory, authentication, headers, streaming, and errors.
Model-specific capabilities, usage rates, and x402 upto settlement require backend implementation and validation. The preview runs local samples; documented contracts do not imply live availability.
Implementation target. This guide specifies the intended product surface. The current frontend uses local samples; it does not call an inference service or collect funds. An endpoint is enabled only after its adapter, ownership, usage, and payment behavior are qualified.
Planned API origin. Examples use https://noemad.dev/v1, the intended product API path. The API is not connected in this frontend preview. MODEL_ID_FROM_DISCOVERY and NOEMAD_API_KEY are placeholders, not published credentials or model IDs. A product API key identifies an account; a separate payment-aware transport must handle spending authorization.
Two related API surfaces
/v1 retains the inference request and response families. Wallet authentication and payment status are additional product endpoints. They do not replace Chat Completions, Responses, Messages, or specialized modality payloads with a single text-only wrapper.
| Method | Path | Purpose |
|---|---|---|
| POST | /v1/chat/completions | Chat Completions JSON / SSE; messages and tools |
| POST | /v1/responses | Responses JSON / event stream |
| POST | /v1/messages | Messages content blocks / event stream |
| POST | /v1/messages/count_tokens | Compatible token count; qualification required |
| POST | /v1/images/generations | Image generation |
| POST | /v1/images/edits | Image editing with a validated source |
| POST | /v1/videos | Create a durable video job |
| GET | /v1/videos/{id} | Read job state and result |
| POST | /v1/audio/speech | Speech synthesis |
| POST | /v1/audio/transcriptions | Audio transcription |
| POST | /v1/files | Owner-scoped upload |
| GET | /v1/artifacts/download/{token} | Expiring owner-scoped artifact delivery |
| POST | /v1/realtime/calls | Negotiate one WebRTC voice session |
| DELETE | /v1/realtime/sessions/{id} | Release a session |
| POST | /v1/embeddings | Create indexed text vectors |
| POST | /v1/rerank | Rank supplied candidate documents |
| POST | /v1/structured-evaluation | Typed answers from state and questions; renamed product route |
| GET | /v1/models | Caller-scoped model discovery |
| GET | /v1/usage | The product owner’s usage; no shared provider balance |
| GET | /calculate/models | Quoteable rate specifications |
| GET | /calculate | Quote a bounded request shape |
| POST | /dashboard/wallet/challenge | Create a wallet sign-in challenge |
| POST | /dashboard/wallet/verify | Verify a signed challenge |
| GET | /api/v1/payments/{quote_id} | Owner-only inference and collection state, actual cost, receipt |
The structured-evaluation route is an explicit product naming change. The precise DTOs and headers remain implementation contracts to freeze with backend fixtures before enabling clients.
Product identity and payment are separate
Inference uses a scoped Noemad product API key or a supported playground session. The key belongs to the wallet account. It can restrict models, expiry, rate, and concurrency; it is not a provider key and does not authorize a token debit.
Authorization: Bearer NOEMAD_API_KEY
Content-Type: application/json
# Messages-compatible authentication, if supported by the frozen contract:
x-api-key: NOEMAD_API_KEYThe intended wallet entry uses /dashboard/wallet/challenge and /dashboard/wallet/verify. Connection is followed by a server-verified challenge; the session must enforce origin, nonce, expiry, cookie security, and CSRF protection.
Common and payment headers
| Header | Use |
|---|---|
| Authorization / x-api-key | Product authentication, according to the endpoint contract |
| Content-Type | Match JSON, multipart, SDP, or binary endpoint requirements |
| Idempotency-Key | One key for one immutable logical mutation |
| X-Request-ID | A bounded caller correlation value; not proof of deduplication |
| PAYMENT-REQUIRED | x402 payment requirements returned with HTTP 402 |
| PAYMENT-SIGNATURE | Client authorization using the pinned x402 v2 upto schema |
| X-Quote-ID | Product extension binding retry to the immutable quote |
| Retry-After | Delay before another eligible status check or safe retry |
| X-Noemad-Request-ID | Proposed product correlation header; final spelling requires fixture agreement |
| X-Noemad-Realtime-Control-Token | Proposed session-release token header; keep it out of logs and URLs |
Generic SDKs do not automatically understand the quote extension. Use a payment-aware transport or local proxy owned by the user. Do not invent a payment signature format or silently sign on a user’s behalf.
402 → authorize maximum → deliver → settle actual
- Authenticate and validate the exact model, body, route, rate, and admission limits.
- Create a quote and return payment requirements before inference.
- The client checks the quote and obtains a bounded wallet authorization.
- Retry the same operation with the same quote, body, and authorization.
- The server binds the nonce once, then streams or returns the inference result.
- After reliable usage is final, calculate and collect the actual amount within the maximum.
- Read
GET /api/v1/payments/{quote_id}for collection state and the verified receipt.
The unused maximum remains in the wallet. Authorization does not transfer the maximum, reserve the wallet balance, or prove future collection will succeed.
Inspect the full response lifecycle
An error before response headers can use an HTTP error status. After a response begins, an error may arrive within an HTTP 200 stream. A buffered response can also contain an error body after initial whitespace. Always inspect the terminal payload.
| Protocol | Terminal failure reference |
|---|---|
| Chat Completions SSE | An error object in a data frame; do not assume partial choices completed |
| Messages SSE | An error event with the Messages error envelope |
| Responses SSE | response.failed with response.error fields |
| Buffered JSON | A complete parsed result or an error envelope |
| Payment collection | A separate owner-only status after inference; never inferred from stream success |
Do not insert product payment events into an established SSE protocol without an explicit compatibility design. A final settlement header cannot be added to already-sent HTTP headers. Partial tool arguments must never be executed.
Error directory
These codes retain the reference surface where applicable; the wallet/payment extension replaces prepaid-credit errors with explicit quote and collection states. Final mappings require endpoint fixtures. Check the machine-readable code and owner-scoped status instead of inferring a cause from a generic message.
| HTTP | Code | Action |
|---|---|---|
| 400 | invalid_client_request_id | Correct the caller request ID. |
| 400 | invalid_file | Validate file bytes, encoding, size, and accepted type. |
| 400 | invalid_image | Validate image bytes, dimensions, and encoding. |
| 400 | invalid_reasoning_effort | Use a level advertised by the selected model. |
| 400 | invalid_request_error | Correct missing fields, invalid JSON, or invalid parameter values. |
| 400 | invalid_tool_history | Match each tool result to its original tool-call ID. |
| 400 | output_token_limit_exceeded | Lower the output cap before a new quote. |
| 400 | request_blocked_by_policy | Review the request; repeated retries do not change a policy decision. |
| 400 | streaming_required | Use a supported streaming transport with the same product payment rules. |
| 400 | unsupported_model_for_endpoint | Choose a model qualified for this endpoint. |
| 400 | unsupported_request_parameter | Remove or correct the unsupported control. |
| 400 | unsupported_tools | Use a supported tool declaration or model. |
| 401 | invalid_api_key | Check the product key; never substitute a provider credential. |
| 402 | payment_required | Review the quote and authorization; a bearer key does not authorize spending. |
| 403 | key_expired / key_revoked | Renew or replace the product key through the owner session. |
| 403 | permission_denied | Check account role, model scope, and ownership. |
| 403 | entitlement_limit | Respect the active per-request offer or account limit. |
| 404 | model_not_found | Refresh authenticated model discovery. |
| 413 | request_too_large | Reduce the conversation or attachment size. |
| 422 | unsupported_input_modality | Choose a compatible model and payload. |
| 429 | client_error_cooldown | Wait and correct repeated invalid requests. |
| 429 | concurrency_limit | Wait for an active operation to finish. |
| 429 | image_requests_temporarily_limited | Honor the delay before another image operation. |
| 429 | ip_rate_limit | Reduce request frequency from the network. |
| 429 | model_rate_limited | Wait before another request to that model. |
| 429 | rate_limit | Honor Retry-After and the account or key limit. |
| 500 | internal_error | Use bounded backoff; preserve the quote and operation reference. |
| 500 | token_count_failed | Record the request ID and retry only when safe. |
| 502 | empty_model_response | No usable output was returned; inspect the operation outcome. |
| 502 | invalid_model_response | Do not treat an unparsable response as success. |
| 502 | invalid_model_tool_arguments | Never execute incomplete or invalid tool arguments. |
| 502 | invalid_model_tool_call | Never execute an undeclared tool. |
| 502 | request_processing_failed | Inspect owner-scoped operation state before another dispatch. |
| 502 | stream_interrupted | Partial text or tool arguments remain incomplete. |
| 502 | tool_generation_limit_exceeded | Do not execute the incomplete action. |
| 503 | model_temporarily_unavailable | Use bounded backoff; the code alone does not identify a cause. |
| 503 | service_busy | Honor Retry-After and avoid duplicate operations. |
| 504 | generation_timeout | Reconcile a possibly dispatched operation before creating another. |
| 504 | stream_idle_timeout | Inspect the terminal outcome and any completed tool actions. |
| 504 | stream_time_limit_exceeded | Treat partial output according to the published delivery policy. |
| 504 | token_count_timeout | Use bounded backoff and retain correlation metadata. |
Retry and support information
Correct input, identity, permission, scope, and policy failures before retrying. For transient failures, use bounded exponential backoff with jitter and honor a numeric Retry-After. Preserve quote, operation, and idempotency identity; do not create a second paid operation because the first timed out.
Save the product request ID, endpoint, model, approximate time, and operation reference. Exclude credentials, raw payment signatures, and private session-control tokens from support messages and public logs.
Ownership and asynchronous resources
Files, jobs, sessions, results, and artifact grants belong to the authenticated product owner. Video uses a durable submit/poll lifecycle. Realtime uses one session across turns and requires explicit release. An expiring artifact URL is a delivery mechanism rather than permanent hosting.