Integration guide

curl https://router.qtum.ai/v1/chat/completions \
  -H "Authorization: Bearer $QTUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      { "role": "user", "content": "Explain Qtum AAL in one paragraph." }
    ]
  }'

from openai import OpenAI

client = OpenAI(
    base_url="https://router.qtum.ai/v1",
    api_key="$QTUM_API_KEY",
)

resp = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Explain Qtum AAL in one paragraph."}],
)
print(resp.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://router.qtum.ai/v1",
  apiKey: process.env.QTUM_API_KEY,
});

const resp = await client.chat.completions.create({
  model: "gpt-5.5",
  messages: [{ role: "user", content: "Explain Qtum AAL in one paragraph." }],
});
console.log(resp.choices[0].message.content);

# Drop-in replacement: change two env vars, keep your existing code.
export OPENAI_BASE_URL=https://router.qtum.ai/v1
export OPENAI_API_KEY=$QTUM_API_KEY

# Then any OpenAI-compatible SDK or tool just works.

curl -X POST https://router.qtum.ai/v1/images/generations \
  -H "Authorization: Bearer $QTUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-2026-04-21",
    "prompt": "a clean product render of a red apple on a white table",
    "size": "1024x1024",
    "n": 1
  }'

import base64
import requests
from openai import OpenAI

client = OpenAI(base_url="https://router.qtum.ai/v1", api_key="$QTUM_API_KEY")

img = client.images.generate(
    model="gpt-image-2-2026-04-21",
    prompt="a clean product render of a red apple on a white table",
    size="1024x1024",
    n=1,
)

# OpenAI image models commonly return b64_json; Qwen/Wan commonly return a URL.
item = img.data[0]
if item.url:
    image_bytes = requests.get(item.url, timeout=60).content
elif item.b64_json:
    image_bytes = base64.b64decode(item.b64_json)
else:
    raise ValueError("image response missing url and b64_json")

with open("output.png", "wb") as f:
    f.write(image_bytes)

curl -X POST https://router.qtum.ai/v1/images/edits \
  -H "Authorization: Bearer $QTUM_API_KEY" \
  -F "model=gpt-image-2-2026-04-21" \
  -F "prompt=replace the background with a clean white studio" \
  -F "image=@./input.png" \
  -F "size=1024x1024" \
  -F "n=1"

curl -X POST https://router.qtum.ai/v1/audio/speech \
  -H "Authorization: Bearer $QTUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-tts-flash",
    "input": "Hello from the Qtum router.",
    "voice": "Cherry",
    "response_format": "mp3"
  }' \
  --output speech.mp3

from openai import OpenAI

client = OpenAI(base_url="https://router.qtum.ai/v1", api_key="$QTUM_API_KEY")

with client.audio.speech.with_streaming_response.create(
    model="qwen3-tts-flash",
    voice="Cherry",
    input="Hello from the Qtum router.",
    response_format="mp3",
) as resp:
    resp.stream_to_file("speech.mp3")

curl -X POST https://router.qtum.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $QTUM_API_KEY" \
  -F "model=qwen3-asr-flash" \
  -F "language=en" \
  -F "response_format=json" \
  -F "file=@./speech.mp3"

from openai import OpenAI

client = OpenAI(base_url="https://router.qtum.ai/v1", api_key="$QTUM_API_KEY")

with open("speech.mp3", "rb") as f:
    tr = client.audio.transcriptions.create(
        model="qwen3-asr-flash",
        file=f,
        language="en",
        response_format="json",
    )
print(tr.text)

# 1) Text-to-video
curl -X POST https://router.qtum.ai/v1/videos \
  -H "Authorization: Bearer $QTUM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: video-job-001" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "prompt": "a calm ocean at sunset, cinematic",
    "resolution": "720p",
    "seconds": 5,
    "mode": "text-to-video"
  }'
# → {"id":"<id>","object":"video","status":"queued"}

# 2) Poll every 2–5 seconds until completed, failed, or cancelled
curl https://router.qtum.ai/v1/videos/<id> \
  -H "Authorization: Bearer $QTUM_API_KEY"

# 3) Download the completed result; the gateway streams the video bytes
curl https://router.qtum.ai/v1/videos/<id>/content \
  -H "Authorization: Bearer $QTUM_API_KEY" -o out.mp4

# --- Image-to-video ---
# Upload the reference once. Images, videos, and MP3/WAV reference audio are accepted;
# purpose is forced to video.
curl https://router.qtum.ai/v1/files \
  -H "Authorization: Bearer $QTUM_API_KEY" \
  -F "[email protected]"
# → {"id":"file-aaaa","object":"file","purpose":"video",...}

curl -X POST https://router.qtum.ai/v1/videos \
  -H "Authorization: Bearer $QTUM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: image-video-job-001" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "prompt": "the reference photo comes alive, gentle push-in",
    "resolution": "720p",
    "seconds": 5,
    "mode": "image-to-video",
    "input_reference": { "type": "image", "url": "file-aaaa" }
  }'

# Multiple references use content[] with one uploaded file id per image_url.url.
# Give each image role=reference_image.

# --- Video-to-video ---
curl https://router.qtum.ai/v1/files \
  -H "Authorization: Bearer $QTUM_API_KEY" \
  -F "[email protected]"
# → {"id":"file-bbbb","object":"file","purpose":"video",...}

curl -X POST https://router.qtum.ai/v1/videos \
  -H "Authorization: Bearer $QTUM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: video-video-job-001" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "prompt": "extend the reference video with a gentle rain effect",
    "resolution": "720p",
    "seconds": 5,
    "mode": "video-to-video",
    "input_reference": { "type": "video", "url": "file-bbbb", "duration": 7.4 }
  }'

# --- Seedance 2.5 reference audio ---
# The upload endpoint accepts MP3/WAV reference audio and returns a reusable file id.
curl https://router.qtum.ai/v1/files \
  -H "Authorization: Bearer $QTUM_API_KEY" \
  -F "[email protected]"
# → {"id":"file-cccc","object":"file","purpose":"video",...}

# Reference audio belongs in content[].audio_url, not input_reference.
curl -X POST https://router.qtum.ai/v1/videos \
  -H "Authorization: Bearer $QTUM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: seedance-audio-job-001" \
  -d '{
    "model": "doubao-seedance-2-5-260628",
    "content": [
      { "type": "text", "text": "cut the scene to the rhythm of audio 1" },
      {
        "type": "audio_url",
        "audio_url": { "url": "file-cccc" },
        "role": "reference_audio"
      }
    ],
    "resolution": "720p",
    "seconds": 5
  }'

# --- HappyHorse Video Edit (special case) ---
# The model derives output duration from the input video. Do not send a top-level
# seconds or duration field. input_reference.duration is required (whole seconds, 3–60).
curl -X POST https://router.qtum.ai/v1/videos \
  -H "Authorization: Bearer $QTUM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: happyhorse-video-edit-001" \
  -d '{
    "model": "happyhorse-1.0-video-edit",
    "prompt": "increase the warm lighting while preserving the scene",
    "resolution": "720p",
    "mode": "video-edit",
    "input_reference": { "type": "video", "url": "file-bbbb", "duration": 7 }
  }'

import time
import requests

BASE = "https://router.qtum.ai/v1"
AUTH = {"Authorization": "Bearer $QTUM_API_KEY"}

# Create a text-to-video task. Use a new idempotency key for each distinct job.
create_headers = {**AUTH, "Idempotency-Key": "video-job-001"}
vid = requests.post(f"{BASE}/videos", headers=create_headers, json={
    "model": "doubao-seedance-2-0-260128",
    "prompt": "a calm ocean at sunset, cinematic",
    "resolution": "720p",
    "seconds": 5,
    "mode": "text-to-video",
}).json()["id"]

# Poll with gradual backoff until a terminal state.
delay = 3
while True:
    task = requests.get(f"{BASE}/videos/{vid}", headers=AUTH).json()
    if task["status"] in ("completed", "failed", "cancelled"):
        break
    time.sleep(delay)
    delay = min(delay * 1.5, 30)

# The content endpoint returns the video body directly after completion.
if task["status"] == "completed":
    with requests.get(f"{BASE}/videos/{vid}/content", headers=AUTH, stream=True) as resp:
        resp.raise_for_status()
        with open("out.mp4", "wb") as f:
            for chunk in resp.iter_content(1024 * 1024):
                f.write(chunk)

# Upload reference media once, then reuse the returned file id in the video request.
with open("ref1.png", "rb") as f:
    image_fid = requests.post(f"{BASE}/files", headers=AUTH,
                              files={"file": f}).json()["id"]

image_job = requests.post(f"{BASE}/videos", headers={
    **AUTH, "Idempotency-Key": "image-video-job-001"
}, json={
    "model": "doubao-seedance-2-0-260128",
    "prompt": "the reference photo comes alive, gentle push-in",
    "resolution": "720p",
    "seconds": 5,
    "mode": "image-to-video",
    "input_reference": {"type": "image", "url": image_fid},
}).json()["id"]

with open("source.mp4", "rb") as f:
    video_fid = requests.post(f"{BASE}/files", headers=AUTH,
                              files={"file": f}).json()["id"]

video_job = requests.post(f"{BASE}/videos", headers={
    **AUTH, "Idempotency-Key": "video-video-job-001"
}, json={
    "model": "doubao-seedance-2-0-260128",
    "prompt": "extend the reference video with a gentle rain effect",
    "resolution": "720p",
    "seconds": 5,
    "mode": "video-to-video",
    "input_reference": {"type": "video", "url": video_fid, "duration": 7.4},
}).json()["id"]

with open("soundtrack.mp3", "rb") as f:
    audio_fid = requests.post(f"{BASE}/files", headers=AUTH,
                              files={"file": f}).json()["id"]

audio_reference_job = requests.post(f"{BASE}/videos", headers={
    **AUTH, "Idempotency-Key": "seedance-audio-job-001"
}, json={
    "model": "doubao-seedance-2-5-260628",
    "content": [
        {"type": "text", "text": "cut the scene to the rhythm of audio 1"},
        {
            "type": "audio_url",
            "audio_url": {"url": audio_fid},
            "role": "reference_audio",
        },
    ],
    "resolution": "720p",
    "seconds": 5,
}).json()["id"]

# HappyHorse Video Edit derives output duration from the input video. Do not
# include top-level seconds or duration. The reference duration is required.
edit_job = requests.post(f"{BASE}/videos", headers={
    **AUTH, "Idempotency-Key": "happyhorse-video-edit-001"
}, json={
    "model": "happyhorse-1.0-video-edit",
    "prompt": "increase the warm lighting while preserving the scene",
    "resolution": "720p",
    "mode": "video-edit",
    "input_reference": {"type": "video", "url": video_fid, "duration": 7},
}).json()["id"]

{
  "id": "b36ad028-1414-4bf5-8975-c7a66bd330a9",
  "object": "video",
  "model": "doubao-seedance-2-0-260128",
  "status": "queued",
  "created_at": 1718500000,
  "completed_at": null,
  "result_file_id": null,
  "seconds": null,
  "usage": null,
  "error": null
}