DOCUMENTATION

Meldport API

Requests, streaming, media jobs, billing, and limits.

01 / QUICKSTART

Your first request

Choose a published model, create one project API key in the console, and send a request to the shared gateway endpoint.

Base URLhttps://meldport-api.eidosstack.com/v1

curl https://meldport-api.eidosstack.com/v1/chat/completions \
  -H "Authorization: Bearer $MELDPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: request-123" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

import os
import requests

response = requests.post(
    "https://meldport-api.eidosstack.com/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {os.environ['MELDPORT_API_KEY']}",
        "Idempotency-Key": "request-123",
    },
    json={
        "model": "YOUR_MODEL_ID",
        "messages": [{"role": "user", "content": "Hello"}],
    },
)
print(response.json())

const response = await fetch(
  "https://meldport-api.eidosstack.com/v1/chat/completions",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer " + process.env.MELDPORT_API_KEY,
      "Content-Type": "application/json",
      "Idempotency-Key": "request-123",
    },
    body: JSON.stringify({
      model: "YOUR_MODEL_ID",
      messages: [{ role: "user", content: "Hello" }],
    }),
  },
);
console.log(await response.json());

02 / AUTHENTICATION

Use a scoped API key

Send the key as a Bearer token. Keys are scoped to a project and can be revoked or rotated from the console without changing your application code.

Keep keys server-side.Never ship a Meldport key in browser JavaScript, mobile bundles, or public repositories.

03 / API KEY POLICY

One key covers the published catalog

A project key created in the dashboard includes catalog reads, LLM inference, image generation, video generation, and audio generation scopes. The model allowlist is intentionally empty, which means every currently published model in that project is available.

Keep the secret server-side.The full key is shown once. Store it in an environment variable, rotate it when exposure is suspected, and revoke old keys from the console. Never paste it into browser code or commit it.

Keys are project-scoped and can carry request, daily, spend, and output limits.
Existing older keys may still have narrower scopes; create a new all-product key when Media access is needed.
Reusing an Idempotency-Key with another payload is rejected rather than creating a second request.

04 / REQUESTS

Request body

The gateway accepts the familiar Chat Completions shape. Model IDs and capabilities are listed in the public model catalog.

Field	Type	Required	Notes
`model`	string	Yes	Stable public model ID.
`messages`	array	Yes	Ordered system, user, assistant, or tool messages.
`stream`	boolean	No	Use Server-Sent Events when true.
`max_tokens`	integer	No	Optional output limit; the model default is used when omitted.
`tools`	array	No	Tool definitions for models that publish tool support.

Idempotency-Key is recommended for non-stream requests. Reusing a key with a different payload returns a conflict instead of silently creating a second request.

{
  "id": "req_01J...",
  "object": "chat.completion",
  "model": "qwen3.8-max",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello"
      }
    }
  ],
  "usage": {
    "prompt_tokens": 8,
    "completion_tokens": 3,
    "total_tokens": 11
  }
}

Available · scope: inference:invokeInput, output, and an explicitly published cache rate are billed per 1M tokens. Retry 429 and safely retryable 5xx responses with backoff; never replay a partly delivered stream automatically.

05 / STREAMING

Read the response as events

Streaming responses use Server-Sent Events. Process each data frame in order and treat data: [DONE] as the terminal marker.

curl -N https://meldport-api.eidosstack.com/v1/chat/completions \
  -H "Authorization: Bearer $MELDPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "stream": true,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Streaming is not replayed.If delivery has started, retry only after your client has decided whether the partial response is safe to discard.

06 / IMAGE API

Run an asynchronous image job

List published image configurations, select one by ID, then submit a prompt. The configuration owns its accepted inputs, output types, maximum charge, and retention window. Use the images:generate scope.

curl https://meldport-api.eidosstack.com/v1/media/configurations \
  -H "Authorization: Bearer $MELDPORT_API_KEY"

# Create a job with a published configuration
curl -X POST https://meldport-api.eidosstack.com/v1/media/jobs \
  -H "Authorization: Bearer $MELDPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: media-request-123" \
  -d '{"configuration_id":"<published-configuration-id>","prompt":"A quiet studio desk"}'

# Poll the job until it is succeeded or failed
curl https://meldport-api.eidosstack.com/v1/media/jobs/<job-id> \
  -H "Authorization: Bearer $MELDPORT_API_KEY"

{
  "id": "job_01J...",
  "configuration_id": "cfg_01J...",
  "state": "queued",
  "billing_state": "held",
  "maximum_charge_microusd": "125000",
  "output_asset_id": null
}

Jobs are asynchronous and settled before download.List configurations first, upload private input assets when the configuration requires them, create an idempotent job, then poll its safe state. A download URL is issued only for a settled output owned by the same project. Internal task IDs, routing URLs, and credentials never appear in the customer response. A repeated Idempotency-Key replays the same compatible job; a new key intentionally requests a new (stochastic) generation even when its prompt and options match an earlier job.

Use catalog records as a reference.The image catalog distinguishes a reference record from an available configuration. Missing values stay marked as not listed, and a catalog record cannot receive traffic until its Meldport configuration is published.

07 / VIDEO API

Submit once, then follow the job state

Video uses /v1/media/jobs with a published video configuration and the videos:generate scope. A create call returns a job, not a finished file. Poll the job until it reaches a terminal state, then request its project-owned output.

curl https://meldport-api.eidosstack.com/v1/media/configurations \
  -H "Authorization: Bearer $MELDPORT_API_KEY"

# Create a job with a published configuration
curl -X POST https://meldport-api.eidosstack.com/v1/media/jobs \
  -H "Authorization: Bearer $MELDPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: media-request-123" \
  -d '{"configuration_id":"<published-configuration-id>","prompt":"A quiet studio desk"}'

# Poll the job until it is succeeded or failed
curl https://meldport-api.eidosstack.com/v1/media/jobs/<job-id> \
  -H "Authorization: Bearer $MELDPORT_API_KEY"

{
  "id": "job_01J...",
  "configuration_id": "cfg_01J...",
  "state": "queued",
  "billing_state": "held",
  "maximum_charge_microusd": "125000",
  "output_asset_id": null
}

Available only for a published configuration.The maximum charge is reserved before work starts and the actual published price settles after success. Reuse the same Idempotency-Key only for the same payload. Retry safe polling requests with backoff; do not submit another generation job just because polling timed out.

08 / AUDIO API · UNAVAILABLE

No customer audio request contract is published yet

Audio model records can be browsed for reference, but Meldport does not advertise a generation endpoint or scope until an audio configuration, output contract, pricing unit, and retention rule pass publication checks.

Do not send production audio traffic.Follow Audio models and the status page. Availability will be recorded here before an endpoint is documented.

09 / MODELS

A catalog record is not automatically available

Meldport uses one identity, project hierarchy, and USD service-credit wallet while keeping each product contract separate.

Surface	Available now	How it works
LLM Gateway	Yes, for published models	Chat Completions requests, streaming, tools, and usage.
Images and video	Only when a verified configuration is published	API-first async jobs, private assets, polling, and signed delivery.
Audio models	Planned, not published	Dedicated page reserved for a verified audio route and output contract.
GPU Compute	Planned, not provisionable	Future whole-server SSH profile after contract and reliability gates.

Why Media is API-first today.Media jobs require an API-key identity, project ownership, a wallet reservation, and an idempotency key. The dashboard never asks you to paste a secret or calls an upstream service directly. Use a server-side request and track the Meldport job ID instead.

10 / GPU COMPUTE · PLANNED

Compute is discovery-only for now

Meldport does not currently publish GPU inventory, regions, provisioning profiles, or an SSH contract. The public Compute page is a truthful launch placeholder until those checks pass.

No compute traffic or provisioning is available.Browse the published model catalog for available API routes, or contact support if you want a launch notification. No ETA, capacity promise, or region list is implied.

10 / ERRORS AND RETRIES

Handle request states and retries

Errors are JSON responses with a stable type and code. Keep the request ID when opening a support ticket.

Log the request ID, not the credential.Record the response status, stable error code, and x-request-id. Never include API keys, prompts, or customer content in a support ticket unless support explicitly asks for a redacted sample.

Status	Meaning	What to do
`401`	Missing or invalid API key.	Check the Bearer token and project scope.
`402`	No selected funding source can cover the hold.	Top up PAYG credit or buy value for the exact model.
`403`	Account, policy, or model access is not eligible.	Review the console state before retrying.
`409`	Idempotency key was reused with another payload.	Use a new key for a new request.
`429`	Rate or capacity limit.	Respect `Retry-After` when present.
`5xx`	Temporary gateway or upstream failure.	Retry only when the response is safely retryable.

11 / PAY AS YOU GO

Settle the actual request against wallet credit

Prices are shown per model in the catalog. Input, output, and cache usage are recorded in the wallet ledger with a request ID for reconciliation.

x-request-id identifies the request across support and usage views.
x-meldport-request-status exposes the safe terminal or in-progress state.
x-meldport-funding records the selected wallet, promo, or package source.
Model pricing is the customer-facing source of truth before traffic is sent.
Admin analytics reports gateway customer charge, recorded cost, gross margin, request volume, and success rate. It does not collect visitor page-view profiles.

12 / MODEL PACKAGES

Prepay value for one exact model

Send X-Meldport-Funding as wallet, promo, package, or auto. Auto checks an eligible promotion, then an exact-model package, then wallet credit when the API key allows fallback.

PAYG wallet charges use the active price version recorded on the request.
A model ending in :free always uses a matching promotion allowance. It never falls back to wallet or package value. Remove the suffix to use the paid model ID.
Monthly free allowances share one input-and-output token pool and reset at 00:00 UTC on the first day of each month. Launch grants are claimed once and use the displayed expiry date.
Model Package value is usable only for its stable model ID and expires on the displayed date.
Input, output, and cache usage debit their actual micro-USD customer charge, not a combined raw-token counter.
package_allowance_unavailable means no active exact-model value can cover the request bound.

A package-funded request reserves its maximum customer charge. Settlement returns unused value. Concurrent requests cannot reserve more than the remaining allowance.

See current offers and expiry terms on the Model Packages page. Use X-Meldport-Funding: package to require package value, or auto to allow the documented fallback order.

13 / LIMITS

Bound traffic at the project and key level

Keys can carry request, daily, spend, and maximum-output limits. The strictest active account, project, key, and route rule wins. Limits are checked before a hold is placed.

A 429 response is safe to retry only after the indicated delay or client backoff.
A validation error is not transient; correct the model, capability, payload size, or output limit before retrying.
Streaming and media retain their own concurrency and output boundaries. Do not infer one product limit from another.

14 / WEBHOOKS · UNAVAILABLE

Polling is the only published media completion contract

Meldport does not currently accept customer webhook destinations or sign completion callbacks. Poll /v1/media/jobs/:idwith backoff. No callback URL, signing secret, or event name is valid until it appears in this section and the OpenAPI contract.

15 / CHANGELOG AND AVAILABILITY

Contract changes are recorded with readiness

Last updated: 2026-09-18

Date	Change	Availability
2026-09-18	Added free-model funding guidance, exact-model package controls, and safer support logging guidance.	Available for published offers
2026-09-12	PAYG and exact-model value funding documented separately; catalog metadata no longer implies an active route.	Available where a route or configuration is published
2026-09-12	Audio requests and customer webhooks remain withheld.	Unavailable

curl https://meldport-api.eidosstack.com/v1/chat/completions \ -H "Authorization: Bearer $MELDPORT_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: request-123" \ -d '{ "model": "YOUR_MODEL_ID", "messages": [{"role": "user", "content": "Hello"}] }'

import os import requests response = requests.post( "https://meldport-api.eidosstack.com/v1/chat/completions", headers={ "Authorization": f"Bearer {os.environ['MELDPORT_API_KEY']}", "Idempotency-Key": "request-123", }, json={ "model": "YOUR_MODEL_ID", "messages": [{"role": "user", "content": "Hello"}], }, ) print(response.json())

const response = await fetch( "https://meldport-api.eidosstack.com/v1/chat/completions", { method: "POST", headers: { Authorization: "Bearer " + process.env.MELDPORT_API_KEY, "Content-Type": "application/json", "Idempotency-Key": "request-123", }, body: JSON.stringify({ model: "YOUR_MODEL_ID", messages: [{ role: "user", content: "Hello" }], }), }, ); console.log(await response.json());

Field

Type

Required

Notes

model

string

Yes

Stable public model ID.

messages

array

Yes

Ordered system, user, assistant, or tool messages.

stream

boolean

Use Server-Sent Events when true.

max_tokens

integer

Optional output limit; the model default is used when omitted.

tools

array

Tool definitions for models that publish tool support.

{ "id": "req_01J...", "object": "chat.completion", "model": "qwen3.8-max", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Hello" } } ], "usage": { "prompt_tokens": 8, "completion_tokens": 3, "total_tokens": 11 } }

curl -N https://meldport-api.eidosstack.com/v1/chat/completions \ -H "Authorization: Bearer $MELDPORT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "YOUR_MODEL_ID", "stream": true, "messages": [{"role": "user", "content": "Hello"}] }'

curl https://meldport-api.eidosstack.com/v1/media/configurations \ -H "Authorization: Bearer $MELDPORT_API_KEY" # Create a job with a published configuration curl -X POST https://meldport-api.eidosstack.com/v1/media/jobs \ -H "Authorization: Bearer $MELDPORT_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: media-request-123" \ -d '{"configuration_id":"<published-configuration-id>","prompt":"A quiet studio desk"}' # Poll the job until it is succeeded or failed curl https://meldport-api.eidosstack.com/v1/media/jobs/<job-id> \ -H "Authorization: Bearer $MELDPORT_API_KEY"

Surface

Available now

How it works

LLM Gateway

Yes, for published models

Chat Completions requests, streaming, tools, and usage.

Images and video

Only when a verified configuration is published

API-first async jobs, private assets, polling, and signed delivery.

Audio models

Planned, not published

Dedicated page reserved for a verified audio route and output contract.

GPU Compute

Planned, not provisionable

Future whole-server SSH profile after contract and reliability gates.

Status

Meaning

What to do

401

Missing or invalid API key.

Check the Bearer token and project scope.

402

No selected funding source can cover the hold.

Top up PAYG credit or buy value for the exact model.

403

Account, policy, or model access is not eligible.

Review the console state before retrying.

409

Idempotency key was reused with another payload.

Use a new key for a new request.

429

Rate or capacity limit.

Respect Retry-After when present.

5xx

Temporary gateway or upstream failure.

Retry only when the response is safely retryable.

Date

Change

Availability

2026-09-18

Added free-model funding guidance, exact-model package controls, and safer support logging guidance.

Available for published offers

2026-09-12

PAYG and exact-model value funding documented separately; catalog metadata no longer implies an active route.

Available where a route or configuration is published

2026-09-12

Audio requests and customer webhooks remain withheld.

Unavailable