バックグラウンド処理とコールバック

履歴書のバックログを解析したり、1時間のインタビューを分析したりする場合、接続を開けたままにしないようにする必要があります。非同期エンドポイントはリンクまたはアップロードを受け付け、すぐに task_idで応答し、作業を私たちの側で実行します。結果をポーリングして収集するか、サーバーに配信してもらうことができます。

非同期エンドポイント

すべての非同期リクエストには、追加として callback_url.

タスクの送信

リストにリンクを含む application/json を送信するか、アップロードを含む multipart/form-data を送信します。マルチパートでは、リンクフィールドを繰り返し送信するか、1行に1つのリンクを送信できます。

curl -X POST https://api.curriculo.me/public/parse/async \
  -H 'Authorization: Bearer key_abc123_yoursecret' \
  -H 'Content-Type: application/json' \
  -d '{"file_urls": ["https://example.com/cvs/candidate_a.pdf", "https://example.com/cvs/candidate_b.pdf"], "callback_url": "https://example.com/curriculo/callback"}'

curl -X POST https://api.curriculo.me/public/summary/async \
  -H 'Authorization: Bearer key_abc123_yoursecret' \
  -H 'Content-Type: application/json' \
  -d '{"media_url": "https://example.com/interviews/interview.mp4", "interview_id": "int_0042", "language": "ko"}'

curl -X POST https://api.curriculo.me/public/translate/async \
  -H 'Authorization: Bearer key_abc123_yoursecret' \
  -H 'Content-Type: application/json' \
  -d '{"texts": ["Senior backend engineer", "Remote within Europe"], "source_language": "en", "target_language": "fr"}'

[！NOTE] JSONリクエストを /translate/asyncに送信する場合、source_language は必須です。 /evaluate/asyncの場合、ジョブを job_details またはとして送信します job_id.

APIは一度に回答しますが、 202:

{ "task_id": "…", "status": "queued", "callback_secret": "whsec_…" }

callback_secret は、 callback_urlを送信した場合のみ返されます。APIキーのように、正確に1回表示されるため、保存してください。

結果の取得

ポーリング

curl https://api.curriculo.me/public/parse/tasks/<task_id> \
  -H 'Authorization: Bearer key_abc123_yoursecret'

タスクは、コールバックが配信されたかどうかに関係なく、作成時に使用した同じキーで読み取ることができます。レスポンスには、コールバックURLやシークレットは含まれません。

コールバック

callback_urlを送信した場合、完了したタスクは application/json としてここにPOSTされ、以下のヘッダーが付加されます

本文は {task_id, op, status, status_code, result, error, completed_at}.

タイムスタンプヘッダーがないため、 task_idで重複した配信を削除する: 同じタスクが複数回到着する可能性がある場合、サーバーが遅くまたはエラーで応答した場合

署名を検証する

生のリクエストボディのHMAC-SHA256を、返された callback_secret をそのまま使用して( whsec_ プレフィックスを含む)キーとして計算する。 sha256= プラス小文字のヘックスダイジェストを X-Curriculo-Signature と定数時間で比較する。受信した生のバイトを使用し、パース前のJSONを拒否する

Python:

import hashlib
import hmac

def is_valid(raw_body: bytes, signature_header: str, callback_secret: str) -> bool:
    # callback_secret is used as-is, including the "whsec_" prefix
    expected = "sha256=" + hmac.new(
        callback_secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header or "")

JavaScript(Node.js):

import crypto from "node:crypto";

// rawBody must be the unparsed request body (a Buffer)
export function isValid(rawBody, signatureHeader, callbackSecret) {
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", callbackSecret).update(rawBody).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(signatureHeader || "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

次に、 X-Curriculo-Task-Id ヘッダー(または task_id ボディ)で重複を削除し、回答する 2xx.

配信とリトライ

• 任意の2xx 以外の回答は、配信失敗としてカウントされ、リダイレクトは実行されない
• 増加する遅延(1、5、15、60分、次に4時間)で配信リトライを行い、約5時間21分で配信がマークされる dead.
• 結果は GET /{op}/tasks/{task_id} のいずれかで読み取れるため、配信ミスによるデータ損失は発生しない

URLの要件

コールバックURLは httpsで、公開可能で、資格情報を含まない必要があります。プライベートネットワーク上的アドレスは拒否されます。

• 送信するリンク(file_urls、resume_urls、media_url)は公開可能な https リンクでなければなりません。公開リンクまたは事前署名付きストレージURL(例：S3)の両方が機能します。
• リダイレクトするリンクは拒否されます。
• リンクによるレコーディングは最大1GBおよび2時間まで可能です。アップロードされたファイルはそれぞれ最大12MBまでに制限されます。

請求

• タスクは、最終的な結果時にその操作として1回請求されます。25個のリンクの非同期解析は$0.01かかります。
• 失敗したタスク(死んだリンク、読み取り不可ファイル)は、決して請求されません。
• レコーディングタスク(/summary/async、/transcribe/async)は、タスクを受け入れたときに2時間の最大値の料金を予約します。その予約に対する十分なクレジットがない場合、リクエストは 400を返します。タスクが失敗した場合、予約は解放されます。

価格と請求について.

タスクによって保持されるデータ

同期操作とは異なり、バックグラウンドタスクは結果を保持するため、ポーリングすることができ、アップロードされたファイルはアカウントの下に保存されます。 データ処理について.