# Sample API calls

Ready-to-run cURL examples for every endpoint on the Phoeniqs Model Service.

Before you start, make sure you have your Base URL, Model Name, and API Key. See How to inference an AI model for a primer.

# List available models

Fetch the full list of models your API Key can reach.

curl --location 'https://maas.phoeniqs.com/v1/models' \
  --header 'Authorization: Bearer <API_Key>'

# Chat completion

Send a prompt to any chat or reasoning model.

curl --location 'https://maas.phoeniqs.com/v1/chat/completions' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <API_Key>' \
  --data '{
    "model": "inference-llama4-maverick",
    "messages": [
      { "role": "user", "content": "How do I make sourdough bread?" }
    ],
    "temperature": 0.7
  }'

# Embeddings

Use v1/embeddings for most cases. If that path is not reachable, fall back to /embeddings.

curl --location 'https://maas.phoeniqs.com/v1/embeddings' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <API_Key>' \
  --data '{
    "model": "inference-bge-m3",
    "input": "OpenAI develops AI models that understand and generate text."
  }'

curl --location 'https://maas.phoeniqs.com/embeddings' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <API_Key>' \
  --data '{
    "model": "inference-bge-m3",
    "input": "OpenAI develops AI models that understand and generate text."
  }'

tip

Normally v1/embeddings works. If it does not, try /embeddings in the URL path.

# Multimodal (text and image)

Send an image URL alongside a text prompt to a vision-capable model.

curl --location 'https://maas.phoeniqs.com/v1/chat/completions' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <API_Key>' \
  --data '{
    "model": "inference-granite-vision-2b",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "What is shown in this image?" },
          {
            "type": "image_url",
            "image_url": {
              "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/a/a9/Example.jpg/800px-Example.jpg"
            }
          }
        ]
      }
    ],
    "temperature": 0.7
  }'

# OCR

Extract text from an image using a dedicated OCR model.

curl --location 'https://maas.phoeniqs.com/v1/chat/completions' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <API_Key>' \
  --data '{
    "model": "inference-deepseek-ocr",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image_url",
            "image_url": {
              "url": "https://ofasys-multimodal-wlcb-3-toshanghai.oss-accelerate.aliyuncs.com/wpf272043/keepme/image/receipt.png"
            }
          },
          { "type": "text", "text": "Free OCR." }
        ]
      }
    ],
    "max_tokens": 2048,
    "temperature": 0.0
  }'

# WhisperX (Transcribe)

POST https://maas.phoeniqs.com/v1/audio/transcriptions

  curl --location 'https://maas.phoeniqs.com/v1/audio/transcriptions' \
    --header 'accept: application/json' \
    --header 'Authorization: Bearer <API_TOKEN>' \
    --form 'model="inference-whisper-large-v3"' \
    --form 'file=@"/path/to/audio.wav"' \
    --form 'response_format="text_with_ts"' \
    --form 'temperature="0"' \
    --form 'vad_method="pyannote"'

Required fields:

model: inference-whisper-large-v3
file: audio file to transcribe

Common optional fields:

response_format: output format. Recommended: text_with_ts
temperature: transcription temperature. Use 0 for deterministic output.
vad_method: voice activity detection method. Recommended: pyannote

Supported audio formats include:

wav
mp3
mp4
m4a
webm
flac
ogg

Example response for response_format="text_with_ts": {"duration": 18.35}

Other available response_format values:

verbose_json: full text, duration, and timestamped segments
verbose_text: plain text transcription
verbose_srt: SRT subtitle format
verbose_vtt: WebVTT subtitle format
conversation: conversation-style transcript
text_with_ts: transcript text with timestamps

# Transform files from one format to another (Example: PDF to markdown)

POST https://maas.phoeniqs.com/v1/convert/file

  curl --location 'https://maas.phoeniqs.com/v1/convert/file'
    --header 'Authorization: Bearer <API_Key>'
    --form 'file=@"/path/to/document.pdf"'
    --form 'to_formats="text"'

Required fields:

file: different file types PDF (.pdf), Word (.docx), PowerPoint (.pptx), spreadsheets(.xlsx, .csv, .ods), OpenDocument files (.odt, .odp), HTML, Markdown, AsciiDoc, LaTeX, common image formats such as PNG and JPEG, XML, JSON Docling, DCLX, EPUB, email, Box Note, audio, and VTT
to_formats: accepts md, text, json, html, html_split_page, yaml, doctags, doclang, dclx, chunks, and vtt Optional:
page_range — Convert selected pages, for example: --form 'page_range=1' --form 'page_range=10'

# See also

How to inference an AI model

../how-to-inference-a-model/

Active Models

../../active-models/