API-Referenz

Authorization: Bearer cvfly_sk_live_abc123def456...

curl -X POST https://convertfly.io/api/v1/jobs \
  -H "Authorization: Bearer cvfly_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "tag": "invoice-batch",
    "tasks": {
      "import-file": {
        "operation": "import/url",
        "url": "https://example.com/invoice.pdf"
      },
      "to-png": {
        "operation": "convert",
        "input": ["import-file"],
        "output_format": "png",
        "options": { "density": 300 }
      },
      "export": {
        "operation": "export/url",
        "input": ["to-png"]
      }
    }
  }'

{
  "id": "cmxr9k2p0",
  "tag": "invoice-batch",
  "status": "processing",
  "created_at": "2026-04-03T10:30:00Z",
  "tasks": [
    { "name": "import-file", "operation": "import/url", "status": "finished" },
    { "name": "to-png",      "operation": "convert",    "status": "processing" },
    { "name": "export",      "operation": "export/url", "status": "waiting" }
  ]
}

curl -X POST https://convertfly.io/api/v1/jobs \
  -H "Authorization: Bearer cvfly_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "tasks": {
      "cover": {
        "operation": "import/url",
        "url": "https://example.com/cover.png"
      },
      "report": {
        "operation": "import/url",
        "url": "https://example.com/report.pdf"
      },
      "merge-all": {
        "operation": "merge",
        "input": ["cover", "report"]
      },
      "export": {
        "operation": "export/url",
        "input": ["merge-all"]
      }
    }
  }'

curl -X POST https://convertfly.io/api/v1/jobs \
  -H "Authorization: Bearer cvfly_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "tasks": {
      "capture": {
        "operation": "capture-website",
        "url": "https://example.com",
        "output_format": "pdf",
        "width": 1280
      },
      "export": {
        "operation": "export/url",
        "input": ["capture"]
      }
    }
  }'

curl https://convertfly.io/api/v1/jobs/job_7kX9mP2qR \
  -H "Authorization: Bearer cvfly_sk_..."

curl "https://convertfly.io/api/v1/jobs?status=finished&per_page=5" \
  -H "Authorization: Bearer cvfly_sk_..."

{
  "data": [ ... ],
  "links": { "first": "?page=1&per_page=5", "last": "?page=9&per_page=5", "prev": null, "next": "?page=2&per_page=5" },
  "meta": {
    "page": 1,
    "per_page": 5,
    "total": 42
  }
}

curl -X DELETE https://convertfly.io/api/v1/jobs/job_7kX9mP2qR \
  -H "Authorization: Bearer cvfly_sk_..."

curl "https://convertfly.io/api/v1/jobs/job_7kX9mP2qR/wait?timeout=120" \
  -H "Authorization: Bearer cvfly_sk_..."

{
  "data": [
    {
      "name": "import-file",
      "operation": "import/url",
      "status": "finished",
      "result": { "file_id": "file_Xk9m..." }
    },
    {
      "name": "convert",
      "operation": "convert",
      "status": "finished",
      "result": { "file_id": "file_Pm3n..." }
    }
  ]
}

{
  "import-file": {
    "operation": "import/url",
    "url": "https://example.com/document.pdf",
    "filename": "document.pdf",
    "headers": {
      "Authorization": "Bearer your-external-token"
    }
  }
}

{
  "upload-file": {
    "operation": "import/upload",
    "filename": "photo.jpg"
  }
}

# The task result will contain the presigned URL
curl -X PUT "https://files.convertfly.io/convertfly-files/..." \
  -H "Content-Type: image/jpeg" \
  --data-binary @photo.jpg

{
  "import-file": {
    "operation": "import/base64",
    "file": "JVBERi0xLjQKJcOkw7zD...",
    "filename": "document.pdf"
  }
}

{
  "convert-hq": {
    "operation": "convert",
    "input": ["import-file"],
    "output_format": "png",
    "options": {
      "density": 300,
      "quality": 95
    }
  }
}

curl -X POST https://convertfly.io/api/v1/webhooks \
  -H "Authorization: Bearer cvfly_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/convertfly",
    "events": ["job.finished", "job.failed"]
  }'

{
  "data": {
    "id": "wh_Abc123...",
    "url": "https://your-app.com/webhooks/convertfly",
    "events": ["job.finished", "job.failed"],
    "signing_secret": "whsec_9f8e7d6c5b4a...",
    "created_at": "2026-04-03T10:30:00Z"
  }
}

{
  "event": "job.finished",
  "timestamp": "2026-04-03T10:31:15Z",
  "data": {
    "id": "job_7kX9mP2qR",
    "status": "finished",
    "tasks": { ... }
  }
}

import crypto from "crypto";

function verifyWebhook(rawBody, signature, timestamp, secret) {
  const signedContent = timestamp + "." + rawBody;
  const expected = "v1=" + crypto
    .createHmac("sha256", secret)
    .update(signedContent)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

import hmac, hashlib

def verify_webhook(raw_body: bytes, signature: str, timestamp: str, secret: str) -> bool:
    signed_content = f"{timestamp}.{raw_body.decode()}"
    expected = "v1=" + hmac.new(
        secret.encode(), signed_content.encode(), hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

{
  "data": {
    "id": "key_Xk9m...",
    "name": "production-server",
    "key": "cvfly_sk_live_abc123def456...",
    "scopes": ["*"],
    "created_at": "2026-04-03T10:30:00Z"
  }
}

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1743681600
Retry-After: 3600

{
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded. 100 requests per 3600s allowed."
}

{
  "code": "INVALID_DATA",
  "message": "Missing required field: output_format",
  "details": {
    "field": "output_format",
    "reason": "required"
  }
}

const res = await fetch("https://convertfly.io/api/v1/jobs", {
  method: "POST",
  headers: {
    "Authorization": "Bearer cvfly_sk_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ tasks: { /* ... */ } }),
});

if (!res.ok) {
  const error = await res.json();
  console.error(`[${error.code}] ${error.message}`);
  // "[INVALID_DATA] Missing required field: output_format"
  return;
}

const { data: job } = await res.json();

HTTP/1.1 201 Created
Content-Type: application/json
X-Credits-Remaining: 9847
X-Credits-Used: 2