開発者 API · クイックスタート

3ステップで初めての API 呼び出し

API キーを用意してサンプルのリクエストを送ると、最初の短縮リンクを作成できます。以下の手順に沿って進めてください。

アカウントと API キーを準備

まずアカウントの確認を済ませ、リクエストの認証に使う API キーを取得してください。

アカウントを確認

登録とアカウント確認を完了してください。基本的なリンク作成は無料プランでも始められますが、機能と API 呼び出し上限はプランによって異なります。

API キーを取得

ダッシュボードの開発者 API ページでキーを取得し、サーバー上の安全な場所に保管してください。

ダッシュボードで API キーを確認

API キーは秘密情報です。公開 Web ページやモバイルアプリのコードに入れず、サーバーでのみ使用してください。

最初の短縮リンクを作成

使用するプログラミング言語の例を選び、最初の短縮リンクを作成してください。すべての例で Vivoldi の標準ドメインを使用します。

初回の呼び出し前に:User-Agent を明示してください

Node.js(サーバー側 JavaScript)や Python などの HTTP クライアントの標準 User-Agent、またはこのヘッダーがないリクエストは、Vivoldi の Web サーバーでブロックされます。例の MyBrand を自社名かサービス名に変え、サーバー側の HTTP リクエストにも同じヘッダーを設定してください。

例を選び、YOUR_API_KEY、MyBrand、url を変更してください。Node.js・PHP・Java のコードは表示されたファイル名で保存し、実行コマンドを入力してください。cURL コマンドはターミナルに貼り付けてください。

Node.js 18+create-link.mjs
const apiKey = "YOUR_API_KEY";
const response = await fetch("https://vivoldi.com/api/link/v2/create", {
  method: "POST",
  headers: {
    "Authorization": "APIKey " + apiKey,
    "Content-Type": "application/json",
    "User-Agent": "MyBrand",
    "Accept-Language": "ko"
  },
  body: JSON.stringify({
    url: "https://your-site.example/your-page",
    domain: "https://vvd.bz"
  })
});
const result = await response.json();
console.log("HTTP " + response.status, result);
実行コマンドnode create-link.mjs
PHP + cURLcreate-link.php
<?php
$apiKey = "YOUR_API_KEY";
$body = json_encode([
    "url" => "https://your-site.example/your-page",
    "domain" => "https://vvd.bz"
]);
$curl = curl_init("https://vivoldi.com/api/link/v2/create");
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: APIKey " . $apiKey,
        "Content-Type: application/json",
        "User-Agent: MyBrand",
        "Accept-Language: ko"
    ],
    CURLOPT_POSTFIELDS => $body,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 10
]);
$result = curl_exec($curl);
if ($result === false) {
    exit(curl_error($curl));
}
echo "HTTP " . curl_getinfo($curl, CURLINFO_HTTP_CODE) . PHP_EOL;
echo $result . PHP_EOL;
curl_close($curl);
実行コマンドphp create-link.php
Java 11+CreateLink.java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class CreateLink {
    public static void main(String[] args) throws Exception {
        String apiKey = "YOUR_API_KEY";
        String body = "{\"url\":\"https://your-site.example/your-page\","
                    + "\"domain\":\"https://vvd.bz\"}";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://vivoldi.com/api/link/v2/create"))
            .timeout(Duration.ofSeconds(10))
            .header("Authorization", "APIKey " + apiKey)
            .header("Content-Type", "application/json")
            .header("User-Agent", "MyBrand")
            .header("Accept-Language", "ko")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println("HTTP " + response.statusCode());
        System.out.println(response.body());
    }
}
実行コマンドjava CreateLink.java
cURL · macOS / LinuxPOST /api/link/v2/create
curl -sS -X POST "https://vivoldi.com/api/link/v2/create" \
  -H "Authorization: APIKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyBrand" \
  -H "Accept-Language: ko" \
  -d '{"url":"https://your-site.example/your-page","domain":"https://vvd.bz"}'

置き換える値:YOUR_API_KEY には自分のキーを、url にはリンク先ページの URL を指定してください。最初のテストでは domain を https://vvd.bz のまま使えます。

応答の言語:エラーメッセージを別の言語で受け取るには、Accept-Language の ko を希望する言語コードに変更してください。

このリンク作成リクエストをもう一度実行すると、新しい短縮リンクが追加で作成される場合があります。テスト中の重複作成に注意してください。

応答で成功を確認

応答本文の code が 0 なら作成は完了です。生成された短縮リンクは result に入ります。

成功時の応答例
{
  "code": 0,
  "message": "",
  "result": "https://vvd.bz/jH3d"
}

確認する2つの項目

code: 0 は成功を示し、result は新しい短縮リンクです。表示したアドレスは例であり、実際の結果はリクエストごとに異なります。

HTTP ステータスが 200 でも、応答本文の code が 0 以外ならエラーです。code と message の両方を確認してください。

うまく動かない場合

認証エラー

401 または 423 の場合は、API キー、アカウントの状態、許可 IP アドレスを確認してください。

リクエストエラー

400 または code が 0 以外の場合は、url、domain、JSON の形式、message を確認してください。

アクセスがブロックされた場合

403 の場合は、まず User-Agent が未設定か、開発ツールの初期値のままになっていないか確認してください。会社名かサービス名を明示して再試行してください。

呼び出し上限

429 の場合は時間を置いて再試行してください。上限はプランによって異なります。

次に読むドキュメント