ConverterHQDevelopers
Entwickler-Aktivierung

API zuerst in der Sandbox beweisen. Erst für Live-Traffic upgraden.

Vom Konto zum ersten API-Aufruf und anschließend kontrolliert in die Produktion.

Starten Sie mit einem Sandbox-Projekt und einem eingeschränkten Testschlüssel. Beweisen Sie zuerst den direkten Storage-Upload und einen echten Job, bevor Sie Produktionszugang buchen.

Produktionstransport: lokale Dateibytes werden über die Files-API direkt in signierten Objektspeicher hochgeladen; Konvertierungen referenzieren danach die eigene File-ID. Die API-Steuerung erhält Metadaten und IDs, nicht die lokalen Dateibytes.

1

Sandbox-Zugang

Sandbox und Produktion

Ein projektgebundener hq_test_... Schlüssel gewährt den begrenzten Evaluierungszugang. hq_live_... Schlüssel bleiben Konten mit aktivem API-Tarif vorbehalten.

converterhq.convert, converterhq.capabilities.read, converterhq.files.read, converterhq.files.write, converterhq.jobs.read, converterhq.jobs.write, converterhq.tasks.read, converterhq.tasks.write, converterhq.usage.read
Vollständige Plattform-Scopes
converterhq.convert, converterhq.capabilities.read, converterhq.files.read, converterhq.files.write, converterhq.jobs.read, converterhq.jobs.write, converterhq.tasks.read, converterhq.tasks.write, converterhq.usage.read, converterhq.workflows.read, converterhq.workflows.write, converterhq.connections.read, converterhq.connections.write, converterhq.webhooks.read, converterhq.webhooks.write, converterhq.logs.read, converterhq.signed_urls.read, converterhq.signed_urls.write, converterhq.realtime.connect
2

Prüfen

Minimalen Schlüssel erstellen

Legen Sie in HQTools ein ConverterHQ-Projekt an und geben Sie dem Quickstart nur die benötigten Files-, Jobs- und Capability-Scopes. Erweitern Sie Rechte erst bei Bedarf.

3

Bereitschaftsprüfung

Kontext prüfen

Rufen Sie GET /v1/me auf und prüfen Sie environment, project_id, scopes und limits, bevor Sie Dateien senden. So vermeiden Sie Vermischung von Sandbox und Produktion.

4

Erste Konvertierung

Direkt in den Storage hochladen und einen echten Job ausführen.

Erstellen Sie ein File, laden Sie die Bytes per PUT auf die signierte Storage-URL, schließen Sie das File ab, senden Sie einen Job und laden Sie das Ergebnis herunter. Dateibytes laufen nicht durch den ConverterHQ-API-Prozess.

Prüfen Sie oben einen Sandbox- oder Live-Schlüssel, um die geführte Konvertierung zu aktivieren.

Erste Sandbox-Konvertierung
set -eu
API='https://sandbox.api.converterhq.io/v1'
KEY="hq_test_..."
FILE='input.docx'
FROM='docx'
TO='pdf'
OUTPUT="result.$TO"

# Allocate metadata, upload bytes directly to storage, then complete the File.
OWNED=$(curl -fsS "$API/files" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg filename "$FILE" '{filename:$filename,content_type:"application/octet-stream"}')")
FILE_ID=$(printf '%s' "$OWNED" | jq -er .id)
UPLOAD_URL=$(printf '%s' "$OWNED" | jq -er .upload.url)
CONTENT_TYPE=$(printf '%s' "$OWNED" | jq -r '.upload.headers["Content-Type"] // "application/octet-stream"')
curl -fsS -X PUT "$UPLOAD_URL" --upload-file "$FILE" -H "Content-Type: $CONTENT_TYPE"
curl -fsS -X POST "$API/files/$FILE_ID/complete" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" -d '{}'

# Reuse this key when retrying this submission after a transport failure.
IDEMPOTENCY_KEY="activation-$FILE_ID"
CONVERSION=$(curl -fsS -X POST "$API/convert" \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg file_id "$FILE_ID" --arg from "$FROM" --arg to "$TO" '{input:{file_id:$file_id},input_format:$from,output_format:$to,options:{}}')")
JOB_ID=$(printf '%s' "$CONVERSION" | jq -er .job_id)
printf 'Job: %s\n' "$JOB_ID"

# Wait up to five minutes. A terminal failure is never treated as a download.
ATTEMPT=0
while [ "$ATTEMPT" -lt 10 ]; do
  JOB=$(curl -fsS "$API/jobs/$JOB_ID/wait?timeout=30" -H "Authorization: Bearer $KEY")
  STATUS=$(printf '%s' "$JOB" | jq -er .status)
  case "$STATUS" in
    succeeded) break ;;
    failed|cancelled)
      printf '%s\n' "$JOB" >&2
      exit 1 ;;
  esac
  ATTEMPT=$((ATTEMPT + 1))
done
if [ "$STATUS" != succeeded ]; then
  printf 'Timed out. Resume with GET %s/jobs/%s/wait?timeout=30\n' "$API" "$JOB_ID" >&2
  exit 1
fi
OUTPUT_FILE_ID=$(printf '%s' "$JOB" | jq -er '[.tasks[] | select(.operation == "convert" and .status == "succeeded") | (.result.file_id // .result.output_file_id) | select(. != null)][0]')
RESULT=$(curl -fsS "$API/files/$OUTPUT_FILE_ID" -H "Authorization: Bearer $KEY")
DOWNLOAD_URL=$(printf '%s' "$RESULT" | jq -er .download_url)
# Signed storage URLs carry their own authorization; do not forward the API key.
curl -fsS "$DOWNLOAD_URL" --output "$OUTPUT"
printf 'Saved %s\n' "$OUTPUT"