# 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.

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

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

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
  }'

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."
  }'

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
  }'

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
  }'

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

Speaker diarization identifies who is speaking and labels the transcript with speakers. It is opt-in per request: add the form field diarize="true" to enable it. No customer-side setup is needed — the diarization model (pyannote) is managed server-side. When diarization is on, each segment and word in the transcript carries a speaker label (SPEAKER_00, SPEAKER_01, …). Without diarize=true no speaker labels are returned.

Diarization optional fields:

• diarize: enable speaker diarization. Default: false.
• min_speakers: minimum number of speakers to detect (1–20). Optional; use together with max_speakers when you know roughly how many people speak.
• max_speakers: maximum number of speakers to detect (1–20). Optional.
• auto_detect_speakers: let the diarization model pick the optimal speaker count automatically; when true, min_speakers/max_speakers are ignored. Default: false.
• vad_method: keep the default pyannote for the best diarization quality (already listed above as a VAD option — it also matters for diarization).

Example request with diarization:

  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/meeting.wav"' \
    --form 'response_format="verbose_json"' \
    --form 'temperature="0"' \
    --form 'vad_method="pyannote"' \
    --form 'diarize="true"' \
    --form 'min_speakers="2"' \
    --form 'max_speakers="4"'

With diarize="true", response_format="verbose_json" returns each segment with a speaker label (excerpt):

{
  "text": "Good morning everyone. Let's get started with the numbers.",
  "duration": 18.35,
  "language": "en",
  "segments": [
    {
      "start": 0.0,
      "end": 3.2,
      "text": "Good morning everyone. Let's get started.",
      "speaker": "SPEAKER_00"
    },
    {
      "start": 3.5,
      "end": 7.1,
      "text": "Sure — I'll share the numbers.",
      "speaker": "SPEAKER_01"
    }
  ]
}

Words are attributed to speakers as well (word-level speaker attribution), so downstream tooling can map every single word to its speaker.

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

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'