本文へスキップ

開発者向け

Vellria APIリファレンス

すべてのモデルを、APIキーで認証する1つのHTTPSエンドポイントから利用できます。

ベースURL
https://vellria.com/v1
認証
Authorization: Bearer vll_...

クイックスタート

#

4回の呼び出しで、APIキーの取得から完成したファイルの受け取りまでが完了します。生成のたびに、カタログに記載された料金分のクレジットが残高から差し引かれます。expectedCostを送ると、料金が変わったリクエストは課金されずに拒否されます(料金と予想コスト)。

  1. APIキーを作成

    ログインして、APIキーページでキーを作成します。キーはvll_で始まり、すべての呼び出しでBearerトークンとして送信します。

  2. モデルを選ぶ

    GET /v1/modelsは、すべてのモデルIDをサイズ、パラメーター、クレジット料金とともに返します。モデル一覧はコードに直接書かず、このエンドポイントから読み込んでください。

  3. 生成を開始

    モデルIDとプロンプトを付けてPOST /v1/generate/imageを呼び出します。レスポンスは202で、生成IDと差し引かれたクレジットが返ります。失敗した生成のクレジットは返還されます。

  4. ポーリングしてダウンロード

    statusがcompletedになるか、error_code付きのfailedになるまで、数秒ごとにGET /v1/generations/{id}を呼び出します。その後、同じキーでoutput_urlをダウンロードします。

2. モデルを選ぶ
curl
curl https://vellria.com/v1/models \
  -H "Authorization: Bearer vll_..."
レスポンス · 200
{
  "image": [
    {
      "id": "vellria-seedream-5-pro",
      "label": "Seedream 5 Pro",
      "kind": "image"
    }
  ],
  "video": [
    {
      "id": "vellria-seedance-2-5",
      "label": "Seedance 2.5",
      "kind": "video"
    }
  ]
}
3. 生成を開始
curl
curl https://vellria.com/v1/generate/image \
  -H "Authorization: Bearer vll_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vellria-seedream-5-pro",
    "prompt": "夜明けの灯台、柔らかな光",
    "size": "1536*1536"
  }'
レスポンス · 202
{
  "id": "gen_3f9a1c7e5b2d4086",
  "status": "processing",
  "model": "vellria-seedream-5-pro",
  "size": "1536*1536",
  "cost_cents": 10
}
4. ポーリングしてダウンロード
curl
curl https://vellria.com/v1/generations/{id} \
  -H "Authorization: Bearer vll_..."
レスポンス · 200
{
  "id": "gen_3f9a1c7e5b2d4086",
  "status": "completed",
  "output_url": "https://vellria.com/v1/generations/gen_3f9a1c7e5b2d4086/file",
  "error_code": null,
  "expires_at": 1791936000000
}
curl
curl -o result.png https://vellria.com/v1/generations/{id}/file \
  -H "Authorization: Bearer vll_..."

認証

#

すべてのリクエストで、AuthorizationヘッダーにAPIキーをBearerトークンとして送信します。キーはvll_プレフィックスで始まり、APIキーページで作成できます。

http
Authorization: Bearer vll_...

エラー

#

すべてのエラーは同じJSONボディで返ります。分岐にはerror.codeを使ってください。error.codeは変わりませんが、error.messageは人が読むためのもので、変更されることがあります。error.paramは原因となったフィールドがある場合にその名前を示し、一部のコードはerror.reasonを追加します(image_unreadable:animated、transparent、too_small、too_large)。エラーを返したリクエストでクレジットが差し引かれたままになることはありません。リクエストエラーは課金前に発生し、開始できなかった生成のクレジットは返還されます。

HTTPステータスコード

HTTP意味
400リクエストが無効です。どのフィールドまたはルールかはerror.codeで示されます。
401APIキーがないか、無効です。
402クレジットが不足しています。
403このアカウントまたはキーでは、このエンドポイントを使えません。
404リソースが存在しないか、別のアカウントのものです。
409料金の変更や生成の実行中など、現在の状態と矛盾するリクエストです。
410ファイルは保存期間を過ぎたため削除されました。
413ファイルまたはボディが大きすぎます。
415Content-Typeが対応している画像形式ではありません。
416要求されたバイト範囲を返せません。
429リクエストが多すぎます。Retry-Afterヘッダーの時間だけ待ってから、再度お試しください。
500Vellria側で予期しないエラーが発生しました。
502モデルまたは決済サービスがリクエストを拒否したか、処理に失敗しました。
503サービスが一時的に利用できません。何も課金されません。

エラーコード

認証とアカウント8authentication_requiredaccount_deletedaccount_suspendedaccount_mergedforbiddenpending_paymentmerge_in_progressaccount_delete_failed
コードHTTP意味
authentication_required401APIキーが送られていないか、無効または失効しています。
account_deleted403アカウントは削除されています。
account_suspended403アカウントは停止されています。
account_merged403アカウントは別のアカウントに統合されました。そのアカウントのキーを使ってください。
forbidden403このエンドポイントはマイページのセッションでのみ使え、APIキーでは使えません。
pending_payment409確定していない支払いがあります。確定してから再度お試しください。
merge_in_progress409アカウントを別のアカウントに連携しています。少し待ってから再度お試しください。
account_delete_failed500アカウントを削除できませんでした。少し待ってから再度お試しください。
リクエストの検証22invalid_bodyinvalid_promptprompt_too_longinvalid_expected_costinvalid_modelinvalid_sizeinvalid_durationinvalid_resolutioninvalid_ratioinvalid_reference_modeinvalid_reference_tokentext_to_video_not_supportedinvalid_<parameter>invalid_typeinvalid_statusinvalid_queryinvalid_idsinvalid_untilinvalid_generation_typethumbnail_unsupportedthumbnail_size_unsupportedinvalid_range
コードHTTP意味
invalid_body400ボディが有効なJSONではないか、必須フィールドがありません。
invalid_prompt400promptがないか、空です。
prompt_too_long400promptがモデルのmax_prompt_lengthを超えています。
invalid_expected_cost400expectedCostが0以上の整数ではありません。
invalid_model400モデルIDがGET /v1/modelsにありません。
invalid_size400sizeがモデルのサイズのいずれでもありません。
invalid_duration400durationがモードの範囲外です。
invalid_resolution400resolutionがモードの解像度のいずれでもありません。
invalid_ratio400ratioがモードのアスペクト比のいずれでもありません。
invalid_reference_mode400reference_modeがframeでもsubjectでもないか、モデルにsubjectモードがありません。
invalid_reference_token400プロンプトが、対応する参照画像のない@imageを参照しています(画像2枚で@image3など)。
text_to_video_not_supported400このモデルは参照画像が必要で、プロンプトだけでは実行できません。
invalid_<parameter>400モデル固有のパラメーターに、モデルが宣言していない値が指定されています。
invalid_type400typeがimageでもvideoでもありません。
invalid_status400statusがqueued、processing、completedのいずれでもありません。
invalid_query400検索テキストが長すぎます。
invalid_ids400idsが1〜50件の生成IDのリストではありません。
invalid_until400untilが有効なタイムスタンプではありません。
invalid_generation_type400参照画像にできるのは画像の生成だけです。
thumbnail_unsupported400サムネイルは画像にのみあります。
thumbnail_size_unsupported400thumbが対応しているサムネイルサイズではありません。
invalid_range416Rangeヘッダーの範囲を返せません。
プロンプト、参照画像、アップロード11content_blockedinvalid_image_urlsreference_not_publicimage_unreadablereference_not_allowedempty_uploadinvalid_imagefile_too_largepayload_too_largeunsupported_media_typeupload_in_use
コードHTTP意味
content_blocked400クレジットが消費される前に、プロンプトが安全フィルターで拒否されました。
invalid_image_urls400image_urlsの形式が正しくないか、モデルに対して画像が少なすぎるか多すぎます。またはモードで必要なのに指定されていません。
reference_not_public400参照画像が認証の必要なファイルURLを指しています。代わりにPOST /v1/uploadsでアップロードしてください。
image_unreadable400参照画像を使えません。理由はerror.reasonに入ります(animated、transparent、too_small、too_large)。
reference_not_allowed403このサービスでは参照画像を使えません。
empty_upload400アップロードのボディが空です。
invalid_image400アップロードが、宣言された形式の読み取り可能な画像ではありません。
file_too_large413ファイルが許容サイズを超えています。
payload_too_large413リクエストボディが許容サイズを超えています。
unsupported_media_type415Content-Typeが対応している画像形式のいずれでもありません。
upload_in_use409このアップロードは生成に使われたため、期限まで保存されます。
生成とファイル8not_foundcontent_expiredgeneration_in_progressgeneration_not_completedupstream_errorreference_rejectedgeneration_unavailablereference_unavailable
コードHTTP意味
not_found404このアカウントに該当するリソースはありません。
content_expired410ファイルは保存期間を過ぎたため削除されました。
generation_in_progress409生成はまだqueuedまたはprocessingです。
generation_not_completed409生成はまだ完了していません。
upstream_error502生成を開始できませんでした。クレジットは返還されます。
reference_rejected502モデルが参照画像を拒否しました。クレジットは返還されます。
generation_unavailable503生成は一時的に利用できません。何も課金されません。
reference_unavailable503参照画像を準備できませんでした。何も課金されません。
クレジットと支払い18insufficient_balanceprice_changedinvalid_packageinvalid_amountinvalid_providerpackage_unavailable_for_providerinvalid_plancheckout_lockedpayment_create_failednot_configuredalready_paidalready_subscribeddowngrade_requires_cancelcheckout_in_progresssubscription_changedsubscription_under_reviewsubscription_not_foundsubscription_cancel_failed
コードHTTP意味
insufficient_balance402アカウントのクレジットが不足しています。
price_changed409料金がexpectedCostと異なります。現在の料金はprice.costにあり、何も課金されません。
invalid_package400package_idがGET /v1/billing/packagesにありません。
invalid_amount400price_amountがmin_usd〜max_usdの範囲外です。
invalid_provider400決済サービスが不明か停止中、またはこの支払いには使えません。
package_unavailable_for_provider400選択した決済サービスでは、このパックを購入できません(パックのexcluded_providersに含まれています。大きなパックのtelegram_starsなど)。支払いは作成されません。
invalid_plan400plan_idがplansのいずれでもありません。
checkout_locked429カード決済の失敗が続いたため、カード決済(provider whop)はしばらくロックされています。暗号資産とTelegramスターは引き続き使えます。Retry-Afterを確認してください。
payment_create_failed502決済サービスが決済ページを開けませんでした。再度お試しください。
not_configured503現在、支払いを受け付けていません。
already_paid409支払いはすでに完了しています。
already_subscribed409すでにこのプランを契約しています。
downgrade_requires_cancel409下位プランに変更するには、先に解約が必要です。
checkout_in_progress409サブスクリプションの決済ページを作成中です。
subscription_changed409決済ページを開いている間にサブスクリプションが変更されました。再読み込みしてから再度お試しください。
subscription_under_review409サブスクリプションの初回の支払いを確認中です。結果が出るまで、新しい決済は開けません。
subscription_not_found404有効なサブスクリプションはありません。
subscription_cancel_failed502解約を確認できませんでした。再度お試しください。
レート制限2rate_limit_exceededreference_rate_limited
コードHTTP意味
rate_limit_exceeded429期間内のリクエストが多すぎます。Retry-Afterの時間だけお待ちください。
reference_rate_limited429参照画像を使うリクエストが、1時間あたりの上限を超えました。
チャット9insufficient_creditsinvalid_jsoninvalid_requestcontext_too_longunsupported_contentdata_url_not_supportedinvalid_image_urltoo_many_imagesempty_response
コードHTTP意味
insufficient_credits402残高が最長の返信(max_tokens)をまかなえません。何も課金されません。
invalid_json400ボディが有効なJSONではありません。
invalid_request400フィールド(messages、role、stream、max_tokens、temperature、top_p)がないか、形式が正しくありません。error.paramに名前が入ります。
context_too_long400メッセージ数または文字数がモデルの上限を超えています。
unsupported_content400contentのパーツがtextでもimage_urlでもないか、userメッセージ以外に画像があります。
data_url_not_supported400画像がdata URLで送られました。POST /v1/uploadsでアップロードし、返されたURLを渡してください。
invalid_image_url400image_url.urlがhttp(s)のURLではありません。
too_many_images4001メッセージまたは1リクエストあたりの画像数が、モデルの上限を超えています。
empty_response502モデルが空の返信を返しました。何も課金されません。
サーバー1internal_error
コードHTTP意味
internal_error500Vellria側で予期しないエラーが発生しました。

失敗した生成

開始後に失敗した生成はHTTPエラーではありません。GET /v1/generations/{id}はstatus failedと以下のいずれかのerror_codeを返し、クレジットは自動的に返還されます。

10件のコードを表示10content_blockedprovider_errorprovider_timeoutprovider_cancelledprovider_unavailableabandonedunknown_providerimage_blockedmoderation_failedreference_rejected
コード意味
content_blocked生成がキューに入った後、プロンプトが安全チェックで拒否されました。
provider_errorモデルが結果を生成できませんでした。
provider_timeoutモデルが時間内に完了しませんでした。
provider_cancelledモデルがジョブをキャンセルしました。
provider_unavailableモデルを利用できませんでした。
abandoned長時間応答がなかったため、ジョブを打ち切りました。
unknown_providerジョブをモデルの実行に紐づけられませんでした。
image_blocked古い記録のみ:現在は使われていないチェックで、参照画像が拒否されました。
moderation_failed古い記録のみ:チェック自体が失敗しました。
reference_rejectedモデルが参照画像を拒否しました。
レスポンス · 400
{
  "error": {
    "message": "vellria-seedance-2-5 does not support reference_mode \"subject\"",
    "type": "invalid_request_error",
    "param": "reference_mode",
    "code": "invalid_reference_mode"
  }
}
レスポンス · 400
{
  "error": {
    "message": "image_urls[0] is animated: use a still, opaque JPEG, PNG, GIF or WebP image of at most 20 MB, 36 megapixels",
    "type": "invalid_request_error",
    "param": "image_urls",
    "code": "image_unreadable",
    "reason": "animated"
  }
}
レスポンス · 409
{
  "error": {
    "message": "Price changed: this request now costs 10 credits",
    "type": "invalid_request_error",
    "param": "expectedCost",
    "code": "price_changed"
  },
  "price": {
    "cost": 10
  }
}

レート制限

#

1分あたり画像20枚、動画10本までです。参照画像を使う生成は、拒否されたものも含めて1時間あたり120回の試行上限も共有し、それを超えると生成エンドポイントはreference_rate_limitedコードを返します。上限を超えるとHTTP 429が返ります。Retry-Afterヘッダーに示された時間だけ待ってから、再度お試しください。

モデルカタログ

#

利用できるモデルとクレジット料金を、{ image: [...], video: [...] }の形で返します。料金表を手元にハードコードせず、このエンドポイントを読み込んでください。各エントリーには、id(modelとして送る値)、label、kind(imageまたはvideo)、family、developer(モデルを開発した企業。Vellriaの名前で提供するモデルではnull)に加えて、textとreferenceの2つのモードがあります。プロンプトだけを送るとモデルはtextモード(テキストから画像、またはテキストから動画)で動作し、同じidに参照画像を1枚以上添付するとreferenceモード(画像から画像、または画像から動画)で動作します。2つを切り替えるための別のidはありません。各モードには、それぞれのsizes(画像)またはresolutions(動画)、default、max_prompt_length(そのモードがpromptと、独自の上限を宣言していない自由入力のテキストパラメーターに適用する文字数上限)、parametersがあります。各サイズと解像度はlabelのほかにratioとtierを持つため、アスペクト比や解像度の段階を知るためにlabelを解析する必要はありません(ratioがadaptiveの場合、出力の比率は入力画像に従います)。reference_imagesはtextモードではnullです。referenceモードでは、そのモードが受け付ける参照画像の最小数と最大数(minとmax)、2枚目以降の参照画像1枚ごとに加算されるextra_credits、参照画像が満たすべきファイル上限を持ちます。参照スロットに固定の役割があるモデルは、その役割を順番にreference_images.rolesに列挙します(現在はすべてのモデルでnull)。image_urlsの最初のURLが最初の役割を、以降のURLが順に次の役割を受け持ち、残りには最後の役割が繰り返し適用されます。

画像モデル

#
  • モデル
    Seedream 5 Pro規制なしvellria-seedream-5-pro
    モード
    テキストから画像画像から画像
    サイズ
    2K · 5種類のサイズ
    料金
    10クレジット
    パラメーター

    テキストから画像 · 全サイズ一律10クレジット + 2枚目以降の参照画像1枚につき1クレジット

    パラメーター指定できる値デフォルト
    image_urls型: string[]https URLを0〜10件(必須)—
    size型: string1536*15361776*13281328*17762048*11521152*20481536*1536
    reasoning型: stringenableddisabledenabled

    画像から画像 · 全サイズ一律10クレジット + 2枚目以降の参照画像1枚につき1クレジット

    パラメーター指定できる値デフォルト
    image_urls型: string[]https URLを1〜10件(必須)—
    モデルページ — Seedream 5 Pro規制なし
  • モデル
    Qwen 3規制なしvellria-qwen-3
    モード
    テキストから画像画像から画像
    サイズ
    1K, 1.5K, 2K · 8種類のサイズ
    料金
    8クレジット
    パラメーター

    テキストから画像 · 全サイズ一律8クレジット

    パラメーター指定できる値デフォルト
    size型: string1024*10241536*10241024*15362048*15361536*20482048*11521152*20482048*20481024*1024
    seed型: integer0〜2147483647省略時はランダムで、レスポンスで返されます
    negative_prompt型: stringテキスト、最大8000文字—

    画像から画像 · 全サイズ一律8クレジット + 2枚目以降の参照画像1枚につき1クレジット

    パラメーター指定できる値デフォルト
    image_urls型: string[]https URLを1〜3件(必須)—
    size型: string1024*10241280*960960*12801280*720720*12801440*14401024*1024
    モデルページ — Qwen 3規制なし
  • モデル
    Qwen 3 Pro規制なしvellria-qwen-3-pro
    モード
    テキストから画像画像から画像
    サイズ
    1K, 1.5K · 3種類のサイズ
    料金
    10クレジット
    パラメーター

    テキストから画像 · 全サイズ一律10クレジット

    パラメーター指定できる値デフォルト
    size型: string1024*10241536*10241024*15361024*1024
    seed型: integer0〜2147483647省略時はランダムで、レスポンスで返されます
    negative_prompt型: stringテキスト、最大8000文字—

    画像から画像 · 全サイズ一律10クレジット + 2枚目以降の参照画像1枚につき1クレジット

    パラメーター指定できる値デフォルト
    image_urls型: string[]https URLを1〜3件(必須)—
    size型: string1024*10241280*960960*12801280*720720*12801440*14401024*1024
    モデルページ — Qwen 3 Pro規制なし
  • モデル
    Qwen Image Edit 2511規制なしvellria-qwen-image-edit-2511
    モード
    テキストから画像画像から画像
    サイズ
    1K, 1.3K · 5種類のサイズ
    料金
    6クレジット
    パラメーター

    テキストから画像 · 全サイズ一律6クレジット

    パラメーター指定できる値デフォルト
    size型: string1024*10241280*960960*12801280*720720*12801024*1024
    seed型: integer0〜2147483647省略時はランダムで、レスポンスで返されます

    画像から画像 · 全サイズ一律6クレジット

    パラメーター指定できる値デフォルト
    image_urls型: string[]https URLを1〜3件(必須)—
    size型: string1K1K
    モデルページ — Qwen Image Edit 2511規制なし
  • モデル
    Qwen Image 2.1規制なしvellria-qwen-image-2-1
    モード
    テキストから画像画像から画像
    サイズ
    1K, 1.2K, 1.3K · 7種類のサイズ
    料金
    7クレジットから
    パラメーター

    テキストから画像 · 全サイズ一律7クレジット

    パラメーター指定できる値デフォルト
    size型: string1024*10241248*832832*12481184*896896*11841376*768768*13761024*1024
    seed型: integer0〜2147483647省略時はランダムで、レスポンスで返されます

    画像から画像 · 全サイズ一律8クレジット + 2枚目以降の参照画像1枚につき1クレジット

    パラメーター指定できる値デフォルト
    image_urls型: string[]https URLを1〜10件(必須)—
    size型: string1K1024*10241248*832832*12481184*896896*11841376*768768*13761K
    モデルページ — Qwen Image 2.1規制なし
  • モデル
    Seedream 5 Lite規制なしvellria-seedream-5-lite
    モード
    テキストから画像画像から画像
    サイズ
    3K, 4K · 8種類のサイズ
    料金
    8クレジット
    パラメーター

    テキストから画像 · 全サイズ一律8クレジット

    パラメーター指定できる値デフォルト
    size型: string3072*30723456*25922592*34563744*24962496*37444096*23042304*40964704*20163072*3072

    画像から画像 · 全サイズ一律8クレジット

    パラメーター指定できる値デフォルト
    image_urls型: string[]https URLを1〜10件(必須)—
    モデルページ — Seedream 5 Lite規制なし
  • モデル
    Seedream 4.5規制なしvellria-seedream-4-5
    モード
    テキストから画像画像から画像
    サイズ
    2K · 8種類のサイズ
    料金
    9クレジット
    パラメーター

    テキストから画像 · 全サイズ一律9クレジット

    パラメーター指定できる値デフォルト
    size型: string2048*20482304*17281728*23042496*16641664*24962848*16001600*28483136*13442048*2048

    画像から画像 · 全サイズ一律9クレジット

    パラメーター指定できる値デフォルト
    image_urls型: string[]https URLを1〜10件(必須)—
    モデルページ — Seedream 4.5規制なし
  • モデル
    Seedream 4規制なしvellria-seedream-4
    モード
    テキストから画像画像から画像
    サイズ
    2K · 5種類のサイズ
    料金
    7クレジット
    パラメーター

    テキストから画像 · 全サイズ一律7クレジット

    パラメーター指定できる値デフォルト
    size型: string2048*20482368*17761776*23682816*15841584*28162048*2048

    画像から画像 · 全サイズ一律7クレジット

    パラメーター指定できる値デフォルト
    image_urls型: string[]https URLを1〜10件(必須)—
    size型: string2K2048*20482368*17761776*23682816*15841584*28162K
    モデルページ — Seedream 4規制なし
  • モデル
    Wan 2.7規制なしvellria-wan-2-7
    モード
    テキストから画像画像から画像
    サイズ
    2K · 1種類のサイズ
    料金
    8クレジット
    パラメーター

    テキストから画像 · 全サイズ一律8クレジット

    パラメーター指定できる値デフォルト
    size型: string2K2K
    seed型: integer0〜2147483647省略時はランダムで、レスポンスで返されます

    画像から画像 · 全サイズ一律8クレジット

    パラメーター指定できる値デフォルト
    image_urls型: string[]https URLを1〜9件(必須)—
    モデルページ — Wan 2.7規制なし
  • モデル
    Bria FIBO 2.0規制なしvellria-bria-fibo-2-0
    モード
    テキストから画像画像から画像
    サイズ
    2K, 1K · 30種類のサイズ
    料金
    10クレジット
    パラメーター

    テキストから画像 · 全サイズ一律10クレジット

    パラメーター指定できる値デフォルト
    size型: string2048*20482304*15361536*23042048*15361536*20481920*15361536*19202048*11521152*20481024*10241248*832832*12481152*864864*11521120*896896*11201408*792792*14081280*800800*12801440*720720*14401568*672672*15681776*592592*17762048*512512*20482320*464464*23202048*2048
    seed型: integer0〜2147483647省略時はランダムで、レスポンスで返されます

    画像から画像 · 全サイズ一律10クレジット

    パラメーター指定できる値デフォルト
    image_urls型: string[]https URLを1〜4件(必須)—
    size型: string1K1K
    モデルページ — Bria FIBO 2.0規制なし
  • モデル
    Bria FIBO 1.5規制なしvellria-bria-fibo-1-5
    モード
    テキストから画像画像から画像
    サイズ
    2K, 2.3K · 7種類のサイズ
    料金
    10クレジット
    パラメーター

    テキストから画像 · 全サイズ一律10クレジット

    パラメーター指定できる値デフォルト
    size型: string2048*20482304*15361536*23042048*15361536*20482048*11521152*20482048*2048
    seed型: integer0〜2147483647省略時はランダムで、レスポンスで返されます

    画像から画像 · 全サイズ一律10クレジット

    パラメーター指定できる値デフォルト
    image_urls型: string[]https URLを1〜4件(必須)—
    size型: string1K1K
    モデルページ — Bria FIBO 1.5規制なし
  • モデル
    MiniMax H3 Image規制なしvellria-minimax-h3-image
    モード
    テキストから画像画像から画像
    サイズ
    1K, 1.2K, 1.3K · 7種類のサイズ
    料金
    8クレジット
    パラメーター

    テキストから画像 · 全サイズ一律8クレジット

    パラメーター指定できる値デフォルト
    size型: string1024*10241248*832832*12481184*896896*11841376*768768*13761024*1024
    seed型: integer0〜2147483647省略時はランダムで、レスポンスで返されます

    画像から画像 · 全サイズ一律8クレジット + 2枚目以降の参照画像1枚につき1クレジット

    パラメーター指定できる値デフォルト
    image_urls型: string[]https URLを1〜9件(必須)—
    size型: string1K1024*10241248*832832*12481184*896896*11841376*768768*13761K
    モデルページ — MiniMax H3 Image規制なし
  • モデル
    Seedream 5 Flash規制なしvellria-seedream-5-flash
    モード
    テキストから画像画像から画像
    サイズ
    2K · 5種類のサイズ
    料金
    8クレジット
    パラメーター

    テキストから画像 · 全サイズ一律8クレジット

    パラメーター指定できる値デフォルト
    size型: string2048*20482368*17761776*23682816*15841584*28162048*2048

    画像から画像 · 全サイズ一律8クレジット

    パラメーター指定できる値デフォルト
    image_urls型: string[]https URLを1〜10件(必須)—
    size型: string2K2048*20482368*17761776*23682816*15841584*28162K
    モデルページ — Seedream 5 Flash規制なし
  • モデル
    Z-Image Turbo規制なしvellria-z-image-turbo
    モード
    テキストから画像
    サイズ
    1K, 1.5K, 2K · 6種類のサイズ
    料金
    2クレジット
    パラメーター

    テキストから画像 · 全サイズ一律2クレジット

    パラメーター指定できる値デフォルト
    size型: string1024*10241536*10241024*15362048*11521152*20482048*20481024*1024
    seed型: integer0〜2147483647省略時はランダムで、レスポンスで返されます
    モデルページ — Z-Image Turbo規制なし
  • モデル
    Anima規制なしvellria-anima
    モード
    テキストから画像画像から画像
    サイズ
    1K, 1.2K, 1.1K, 1.3K · 7種類のサイズ
    料金
    5クレジット
    パラメーター

    テキストから画像 · 全サイズ一律5クレジット

    パラメーター指定できる値デフォルト
    size型: string1024*10241248*832832*12481168*880880*11681360*768768*13601024*1024
    seed型: integer0〜2147483647省略時はランダムで、レスポンスで返されます

    画像から画像 · 全サイズ一律5クレジット

    パラメーター指定できる値デフォルト
    image_urls型: string[]https URLを1〜1件(必須)—
    size型: string1K1K
    モデルページ — Anima規制なし
  • モデル
    Vellria Anime Pro Spicy規制なしvellria-anime-pro-spicy
    モード
    テキストから画像画像から画像
    サイズ
    2K · 5種類のサイズ
    料金
    10クレジット
    パラメーター

    テキストから画像 · 全サイズ一律10クレジット + 2枚目以降の参照画像1枚につき1クレジット

    パラメーター指定できる値デフォルト
    image_urls型: string[]https URLを0〜10件(必須)—
    size型: string1536*15361776*13281328*17762048*11521152*20481536*1536

    画像から画像 · 全サイズ一律10クレジット + 2枚目以降の参照画像1枚につき1クレジット

    パラメーター指定できる値デフォルト
    image_urls型: string[]https URLを1〜10件(必須)—
    モデルページ — Vellria Anime Pro Spicy規制なし
  • モデル
    Pruna P-Image規制なしvellria-p-image
    モード
    テキストから画像画像から画像
    サイズ
    1K, 1.2K, 1.1K, 1.3K · 7種類のサイズ
    料金
    4クレジット
    パラメーター

    テキストから画像 · 全サイズ一律4クレジット

    パラメーター指定できる値デフォルト
    size型: string1024*10241216*832832*12161152*896896*11521344*768768*13441024*1024
    seed型: integer0〜2147483647省略時はランダムで、レスポンスで返されます

    画像から画像 · 全サイズ一律4クレジット

    パラメーター指定できる値デフォルト
    image_urls型: string[]https URLを1〜5件(必須)—
    size型: string1K1024*10241216*832832*12161152*896896*11521344*768768*13441K
    モデルページ — Pruna P-Image規制なし
  • モデル
    Flux 2 Klein 9B規制なしvellria-flux-2-klein-9b
    モード
    テキストから画像画像から画像
    サイズ
    1K, 1.2K, 1.1K, 1.3K · 7種類のサイズ
    料金
    5クレジット
    パラメーター

    テキストから画像 · 全サイズ一律5クレジット

    パラメーター指定できる値デフォルト
    size型: string1024*10241248*832832*12481152*864864*11521360*768768*13601024*1024
    seed型: integer0〜2147483647省略時はランダムで、レスポンスで返されます

    画像から画像 · 全サイズ一律5クレジット

    パラメーター指定できる値デフォルト
    image_urls型: string[]https URLを1〜3件(必須)—
    size型: string1K1024*10241248*832832*12481152*864864*11521360*768768*13601K
    モデルページ — Flux 2 Klein 9B規制なし
  • モデル
    Moss Image規制なしvellria-moss-image
    モード
    テキストから画像
    サイズ
    1K, 1.2K, 1.1K, 1.3K, 1.4K, 1.5K, 1.7K · 15種類のサイズ
    料金
    5クレジット
    パラメーター

    テキストから画像 · 全サイズ一律5クレジット

    パラメーター指定できる値デフォルト
    size型: string1024*10241248*832832*12481168*880880*11681136*912912*11361360*768768*13601440*720720*14401552*656656*15521760*576576*17601024*1024
    seed型: integer0〜2147483647省略時はランダムで、レスポンスで返されます
    モデルページ — Moss Image規制なし
  • モデル
    Jib Mix Qwen Image規制なしvellria-jib-mix-qwen-image
    モード
    テキストから画像
    サイズ
    1K, 1.2K, 1.1K, 1.3K · 7種類のサイズ
    料金
    5クレジット
    パラメーター

    テキストから画像 · 全サイズ一律5クレジット

    パラメーター指定できる値デフォルト
    size型: string1024*10241248*832832*12481152*864864*11521360*768768*13601024*1024
    seed型: integer0〜2147483647省略時はランダムで、レスポンスで返されます
    モデルページ — Jib Mix Qwen Image規制なし
  • モデル
    Z-Image Spicy規制なしvellria-z-image-spicy
    モード
    テキストから画像
    サイズ
    1K, 1.5K · 7種類のサイズ
    料金
    4クレジット
    パラメーター

    テキストから画像 · 全サイズ一律4クレジット

    パラメーター指定できる値デフォルト
    size型: string1024*10241024*15361536*10241152*15361536*1152864*15361536*8641024*1536
    seed型: integer0〜2147483647省略時はランダムで、レスポンスで返されます
    モデルページ — Z-Image Spicy規制なし
  • モデル
    Z-Image Spicy Pro規制なしvellria-z-image-spicy-pro
    モード
    テキストから画像
    サイズ
    1K, 2K, 2.5K · 8種類のサイズ
    料金
    5クレジット
    パラメーター

    テキストから画像 · 全サイズ一律5クレジット

    パラメーター指定できる値デフォルト
    size型: string1024*10242048*20481536*20482048*15361680*25202520*16801440*25602560*14401024*1024
    seed型: integer0〜2147483647省略時はランダムで、レスポンスで返されます
    モデルページ — Z-Image Spicy Pro規制なし
  • モデル
    Qwen Image Edit Spicy規制なしvellria-qwen-image-edit-spicy
    モード
    テキストから画像画像から画像
    サイズ
    1K · 1種類のサイズ
    料金
    10クレジット
    パラメーター

    テキストから画像 · 全サイズ一律10クレジット

    パラメーター指定できる値デフォルト
    image_urls型: string[]https URLを1〜3件(必須)—
    size型: string1K1K
    seed型: integer0〜2147483647省略時はランダムで、レスポンスで返されます

    画像から画像 · 全サイズ一律10クレジット

    モデルページ — Qwen Image Edit Spicy規制なし

GET/v1/models

すべてのモデルを、モード、サイズまたは解像度、パラメーター、クレジット料金とともに返します。公開:APIキーなしで呼び出せます。
curl
curl https://vellria.com/v1/models \
  -H "Authorization: Bearer vll_..."
#

画像生成

#

テキストのプロンプトから画像を生成します。同じモデルIDでimage_urlsに参照画像を添付すると、画像の編集やスタイル変更もできます。呼び出しはすぐにHTTP 202と生成IDを返し、画像はバックグラウンドで生成されます。statusがcompletedになるまでGET /v1/generations/{id}をポーリングし、output_urlからダウンロードしてください。選択したサイズのクレジットは生成開始時に差し引かれ、失敗した場合は自動的に返還されます。すべてのモデルのサイズ、参照画像の上限、パラメーター、料金はGET /v1/modelsから取得できます。

POST/v1/generate/image

画像生成を開始します。生成ID付きの202を返すので、結果をポーリングしてください。

パラメーター

パラメーター説明
modelstring · ボディ任意GET /v1/modelsのモデルID。
promptstring · ボディ必須生成する内容。モデルのmax_prompt_length文字まで指定できます。
sizestring · ボディ任意モデルのsizesにあるサイズID。省略時はモデルのデフォルトサイズです。
image_urlsstring[] · ボディ任意参照画像のURL。POST /v1/uploadsのアップロードURL、または任意の公開https URLを指定します。モデルが受け付ける枚数とファイル上限はreference_imagesにあります。
image_urlstring · ボディ任意参照画像が1枚の場合の省略形。
expectedCostinteger · ボディ任意省略可能な料金チェック。このリクエストにかかると見込むクレジット数です。料金が異なる場合は409 price_changedを返し、何も課金されません。

各モデルは、GET /v1/modelsのエントリーのparametersに記載されたパラメーター(seedなど)も受け付けます。モデルが宣言する範囲外の値はinvalid_<parameter>を返します。

curl
curl https://vellria.com/v1/generate/image \
  -H "Authorization: Bearer vll_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vellria-qwen-3",
    "prompt": "A cat asleep in space, cinematic light",
    "size": "1024*1024",
    "seed": 42
  }'
#

各モデルのサイズ、パラメーター、料金は画像モデルをご覧ください。

料金と予想コスト

#

どちらの生成エンドポイントも、省略可能なexpectedCostを受け付けます。これは、GET /v1/modelsの料金(モデル、サイズまたは解像度、長さ、追加の参照画像)から算出した、このリクエストにかかると見込むクレジット数です。実際に課金される額と異なる場合、呼び出しはprice_changedコード付きのHTTP 409を返し、price.costに現在の料金が入ります。この場合は何も課金されず、生成も開始されません。チェックが不要な場合はフィールドを省略します。

動画生成

#

image_urlsに参照画像を添付し、reference_modeでモデルが画像をどう使うかを選びます。デフォルトのframe(フィールドを省略した場合も同じ)は、その画像から動画を始めます。subjectは各画像を、動画に登場させたい人物・物・場所の参照として扱い、プロンプトではimage_urlsの順に@image1、@image2…として参照します(大文字と小文字は区別しません)。subjectモードは、GET /v1/modelsのエントリーにsubjectブロックがあるモデルでのみ使えます(それ以外のモデルではnull)。このブロックには独自のresolutions、durations、ratios、parametersがあり、参照画像の上限はsubject.reference_images.max、トークンのパターンはsubject.reference_tokenにあります。料金は同じモデルの画像から動画と同じで、参照画像ごとの追加料金はありません。エラーはすべてHTTP 400で、クレジットが消費される前に返ります。値がframeでもsubjectでもない場合、またはモデルにsubjectモードがない場合はinvalid_reference_mode、subjectモードで参照画像がない場合やモデルの上限を超える場合はinvalid_image_urls、プロンプトが対応する参照画像のない@imageを参照している場合(画像2枚で@image3など)はinvalid_reference_tokenです。frameモードでは、@image1はただのテキストとして扱われます。

POST/v1/generate/video

プロンプトから動画生成を開始します。参照画像も添付できます。生成ID付きの202を返します。

パラメーター

パラメーター説明
modelstring · ボディ任意GET /v1/modelsのモデルID。
promptstring · ボディ必須生成する内容。モデルのmax_prompt_length文字まで指定できます。
durationinteger · ボディ任意秒単位の長さ。モードのduration範囲内で指定し、範囲外の値は400を返します。
resolutionstring · ボディ任意モードのresolutionsにある解像度ID。
ratiostring · ボディ任意モードのratiosにあるアスペクト比ID。
reference_modeframe | subject · ボディ任意frame(デフォルト)は最初の画像から動画を始めます。subjectはすべての画像を参照として使い、プロンプトでは@image1、@image2…として参照します。
image_urlsstring[] · ボディ任意参照画像のURL。POST /v1/uploadsのアップロードURL、または任意の公開https URLを指定します。モデルが受け付ける枚数とファイル上限はreference_imagesにあります。
image_urlstring · ボディ任意参照画像が1枚の場合の省略形。
expectedCostinteger · ボディ任意省略可能な料金チェック。このリクエストにかかると見込むクレジット数です。料金が異なる場合は409 price_changedを返し、何も課金されません。

各モデルは、GET /v1/modelsのエントリーのparametersに記載されたパラメーター(seedなど)も受け付けます。モデルが宣言する範囲外の値はinvalid_<parameter>を返します。

curl
curl https://vellria.com/v1/generate/video \
  -H "Authorization: Bearer vll_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vellria-wan-3",
    "prompt": "Ocean waves at sunset, slow dolly forward",
    "duration": 5,
    "resolution": "1080p"
  }'
subjectモード:image_urlsはプロンプトで参照する人物や物
curl
curl https://vellria.com/v1/generate/video \
  -H "Authorization: Bearer vll_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vellria-wan-3",
    "reference_mode": "subject",
    "image_urls": [
      "https://vellria.com/v1/uploads/{id1}",
      "https://vellria.com/v1/uploads/{id2}"
    ],
    "prompt": "@image1 walks along the beach at sunset holding @image2",
    "duration": 5,
    "resolution": "1080p"
  }'
#

各モデルのサイズ、パラメーター、料金は動画モデルをご覧ください。

チャット

#

規制なしのチャットとロールプレイ。キャラクターを演じる、物語を一緒に書く、ただ話すといった使い方ができ、画像を共有して読み取らせることもできます。100万トークンあたり入力50クレジット(US$0.50)、出力200クレジット(US$2.00)。 OpenAI互換です。OpenAI SDKのベースURLをVellriaに向け、vll_キーを使います。各返信はトークン単位でクレジットから課金されます。

詳細

100万トークンあたり:入力50クレジット(US$0.50)・キャッシュ入力5クレジット(US$0.05)・出力200クレジット(US$2.00)。

  • 返信はフィルタリングされません。Vellriaはこのエンドポイントにコンテンツのフィルタリングを追加しないため、エンドユーザーに対するコンテンツ管理は開発者の責任で行ってください。メッセージの前に、モデルの名乗りを定める1行の指示が入りますが、そのトークンは課金されず、usageにも含まれません。
  • 画像:userメッセージにimage_urlパーツを追加します。1メッセージあたり最大4枚、1リクエストあたり最大8枚です。先にPOST /v1/uploadsで画像をアップロードし、返されたURLを渡します。data URLはdata_url_not_supportedで拒否されます。
  • max_tokensのデフォルトは1024、最大は4096です。reasoningやthinkingのフィールドは無視され、返信に推論が含まれることはありません。
  • stream: trueを指定すると、返信はOpenAIのチャンク形式のServer-Sent Events(data:行)で届き、data: [DONE]で終わります。その直前のチャンクはchoicesが空で、usageと課金額を含みます。ストリーム開始後のエラーはdata: {"error": …}イベントとして届きます。すでにテキストが送られていればそのテキスト分が課金され(usageチャンクはエラーの直前に届きます)、そうでなければ何も課金されません。
  • すべての返信には、OpenAIのusageに加えて、credits_charged(端数を含むクレジット)、cost_usd、credits_debited(今回残高から差し引かれた整数のクレジット。端数はアカウント上で累積されます)が含まれます。拒否、失敗、空の返信は課金されません。キャンセルしたストリームは、すでに生成されたトークン分が課金されます。
  • リクエストの開始前に、残高が最長の返信をまかなえる必要があります(不足時は402 insufficient_credits)。1分あたりのリクエスト数と同時に実行できるリクエスト数は、アカウントごとに制限されます(429 rate_limit_exceeded)。
javascript
import OpenAI from "openai"

const client = new OpenAI({
  apiKey: "vll_...",
  baseURL: "https://vellria.com/v1",
})

const stream = await client.chat.completions.create({
  model: "vellria-uncensored-chat",
  messages: [{ role: "user", content: "物語を始めましょう。" }],
  stream: true,
})
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "")
}

POST/v1/chat/completions

会話を送信し、モデルの返信を一括またはストリーミングで受け取ります。OpenAI互換で、トークン単位で課金されます。

パラメーター

パラメーター説明
modelstring · ボディ必須GET /v1/modelsのtextグループにあるチャットモデルのID。
messagesobject[] · ボディ必須会話。role(system、user、assistant)とcontentを持つオブジェクトです。contentは文字列、またはuserメッセージではtextとimage_urlのパーツのリストです。画像URLはPOST /v1/uploadsで取得します。
streamboolean · ボディ任意trueでは返信をServer-Sent Eventsでストリーミングし、false(デフォルト)では一括で返します。
max_tokensinteger · ボディ任意返信の最大トークン数。省略時はモデルのdefault_max_tokensで、上限はmax_output_tokensです。
temperaturenumber · ボディ任意サンプリング温度。0〜2の範囲で指定します。
top_pnumber · ボディ任意Nucleusサンプリング。0より大きく1以下の値です。
curl
curl https://vellria.com/v1/chat/completions \
  -H "Authorization: Bearer vll_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vellria-uncensored-chat",
    "messages": [
      {"role": "system", "content": "皮肉屋の宇宙海賊Miraとして振る舞ってください。キャラクターは崩さないこと。"},
      {"role": "user", "content": "Mira、今夜はどこに向かいますか?"}
    ],
    "max_tokens": 512
  }'
curl
curl -N https://vellria.com/v1/chat/completions \
  -H "Authorization: Bearer vll_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vellria-uncensored-chat",
    "stream": true,
    "messages": [
      {"role": "user", "content": [
        {"type": "text", "text": "このキャラクターの特徴を説明して、最初のセリフを書いてください。"},
        {"type": "image_url", "image_url": {"url": "<upload_url>"}}
      ]}
    ]
  }'
#

画像アップロード

#

参照画像を自分でホスティングする必要はありません。このエンドポイントにファイルをそのままボディとして送ると公開URLが返るので、そのURLをimage_urlsで使います。Content-Typeヘッダーは必須で、ボディと一致している必要があります。対応形式はimage/jpeg、image/png、image/webp、image/bmp、image/gifで、1ファイルの上限は20 MBです。参照画像として使う画像は、20 MB以下の静止画のJPEG、PNG、GIF、WebPで、透過部分がなく、選択したモデルが公開しているファイル上限内である必要があります。上限は`GET /v1/models`がモデルごとに`reference_images.limits`(バイト数、辺のピクセル数、メガピクセル)として返します。上限外の参照画像は、クレジットが消費される前にHTTP 400と`image_unreadable`(reasonは`too_small`または`too_large`)で拒否されます。EXIFなどのメタデータは、ファイルの保存時に削除されます。URLには推測できないIDが含まれ、どの生成にも使われなければアップロードの24時間後に削除されます(レスポンスのexpires_atフィールド)。生成の参照画像として使われた場合はアップロードの48時間後まで保存されます(生成ファイルの保存期間よりはるかに短い期間です)。期限が切れると、エンドポイントはHTTP 410とcontent_expiredを返します。生成ファイル自体のURL(/v1/generations/{id}/file)は認証が必要なため、参照画像には使えません。生成エンドポイントは、クレジットが消費される前にreference_not_publicコード付きのHTTP 400で拒否します。代わりにここでファイルをアップロードするか、POST /v1/generations/{id}/referenceで画像の生成結果を公開参照URLに変換してください。参照画像の内容はチェックされません。写っている人物や物を理由に拒否される画像はなく、この経路にimage_blockedによる拒否はありません。参照画像を拒否するのは、ファイル自体を読み取れない場合だけです。読み取れない画像はHTTP 400とimage_unreadableを返し、原因に応じてreasonにanimated、transparent、too_small、too_largeが入ります。ただし、モデル自体が処理できない参照画像を拒否することはあります。その場合、生成はerror_code reference_rejectedで失敗し、クレジットは自動的に返還されます。参照画像を準備できなかった場合、リクエストはHTTP 503とreference_unavailableを返し、クレジットは消費されません。APIキーで送られたプロンプトは、送られたとおりにモデルへ渡されます。拒否されるのは未成年者への性的虐待に関わるリクエストだけで、HTTP 400とcontent_blockedコードが返ります。すべての参照画像は、まずアップロードとして保存され(外部URLで指定された画像はメタデータを除いてコピーされます)、生成サービスはその固定URLから取得します。そのため、生成サービスが受け取るのは保存されたファイルそのものです。

POST/v1/uploads

参照画像をそのままボディとしてアップロードし、image_urlsで使える公開URLを受け取ります。

パラメーター

パラメーター説明
Content-Typeimage/* · ヘッダー必須ボディの画像形式:image/jpeg、image/png、image/webp、image/bmp、image/gif。
bodybinary · ボディ必須画像ファイルそのもの(最大20 MB)。
curl
curl https://vellria.com/v1/uploads \
  -H "Authorization: Bearer vll_..." \
  -H "Content-Type: image/png" \
  --data-binary @reference.png
#

GET/v1/uploads/{id}

アップロードした画像を取得します。公開:APIキーなしで取得でき、推測できないIDがアクセス権になります。

パラメーター

パラメーター説明
idstring · パス必須アップロードID。
curl
curl -o reference.png https://vellria.com/v1/uploads/{id}
#

DELETE/v1/uploads/{id}

どの生成にも使われていないアップロードを削除します。所有者のみ実行でき、204を返します。使用済みのアップロードは409 upload_in_useを返し、期限が来ると自動的に削除されます。

パラメーター

パラメーター説明
idstring · パス必須アップロードID。
curl
curl -X DELETE https://vellria.com/v1/uploads/{id} \
  -H "Authorization: Bearer vll_..."
#

POST/v1/generations/{id}/reference

完了した画像生成を、image_urlsに渡せる公開の参照アップロードに変換します。

パラメーター

パラメーター説明
idstring · パス必須生成ID。
curl
curl -X POST https://vellria.com/v1/generations/{id}/reference \
  -H "Authorization: Bearer vll_..."
#

生成ステータスの確認

#

生成は非同期で実行され、statusはqueued → processing → completedと進みます。生成が失敗した場合、クレジットは自動的に返還されます。GET /v1/generationsの一覧に表示されるのは、完了済みと実行中の生成だけです。失敗した生成は一覧と合計件数から除外されますが、GET /v1/generations/{id}では30日間、error_code付きで引き続き返されます。その後、失敗した記録は削除され、GET /v1/generations/{id}とそのファイルエンドポイントはnot_foundコード付きのHTTP 404を返します。?status=failedで一覧を絞り込むと400が返り、失敗した生成はGET /v1/billing/historyの生成側(generations_totalを含む)からも除外されます。まだ通知されていない失敗は、GET /v1/generations/failuresで確認できます。レスポンスにはcount、refunded_cents(実際に返還されたクレジット。返還がなかった場合は0)、untilと、dataに最新の最大5件が入ります。POST /v1/generations/failures/seenで既読にできます。ids(生成IDを1〜50件)またはuntil(そのタイムスタンプまでのすべての失敗)のどちらかを送ります。他のアカウントのIDは無視され、同じ失敗が通知されるのは、端末をまたいで1回だけです。

GET/v1/generations/{id}

1件の生成を取得します。status、完了後のoutput_url、失敗時のerror_codeが返ります。

パラメーター

パラメーター説明
idstring · パス必須生成ID。
curl
curl https://vellria.com/v1/generations/{id} \
  -H "Authorization: Bearer vll_..."
#

GET/v1/generations

生成を一覧表示します。ページングと絞り込みに対応し、失敗した生成は含まれません。

パラメーター

パラメーター説明
limitinteger · クエリ任意ページサイズ。1〜50(デフォルト20)。
offsetinteger · クエリ任意スキップする行数。
typeimage | video · クエリ任意imageまたはvideo。
statusstring · クエリ任意queued、processing、completedのいずれか。failedは400を返します。
modelstring · クエリ任意このモデルIDで生成したものだけを返します。
favoritesstring · クエリ任意1またはtrue:お気に入りのみ。
availablestring · クエリ任意1またはtrue:ファイルがまだ保存されている生成のみ。期限切れや削除済みのファイルはdataとtotalから除外されます。
qstring · クエリ任意プロンプトとモデルを検索します。
curl
curl "https://vellria.com/v1/generations?type=image" \
  -H "Authorization: Bearer vll_..."
#

GET/v1/generations/{id}/file

生成ファイルをダウンロードします。APIキーが必要なため、参照URLとしては使えません。

パラメーター

パラメーター説明
idstring · パス必須生成ID。
downloadstring · クエリ任意任意の値:ファイルを添付ファイルとして返します。
thumbstring · クエリ任意サムネイルのサイズ(画像のみ)。
curl
curl -o result.png https://vellria.com/v1/generations/{id}/file \
  -H "Authorization: Bearer vll_..."
#

GET/v1/generations/failures

まだ通知されていない失敗した生成と、それに対して返還されたクレジットを返します。
curl
curl https://vellria.com/v1/generations/failures \
  -H "Authorization: Bearer vll_..."
#

POST/v1/generations/failures/seen

失敗を既読にします。IDで指定するか、タイムスタンプまでをまとめて指定します。

パラメーター

パラメーター説明
idsstring[] · ボディ任意既読にする生成ID(1〜50件)。
untilinteger · ボディ任意Unixミリ秒のタイムスタンプ(GET /v1/generations/failuresのuntilの値)。それまでのすべての失敗が既読になります。
curl
curl -X POST https://vellria.com/v1/generations/failures/seen \
  -H "Authorization: Bearer vll_..." \
  -H "Content-Type: application/json" \
  -d '{"ids": ["gen_..."]}'
#

クレジットの追加

#

クレジットは、ホスティング型の決済ページで購入します。GET /v1/billing/packagesは単一のパック一覧を返し、各パックにはid、usd価格、クレジット数があります。あわせて、任意の金額の範囲としてmin_usdとmax_usdも返します。これらはハードコードせず、エンドポイントから読み込んでください。POST /v1/billing/create-checkoutは、一覧のpackage_idか、30〜10000 USDの任意の金額price_amount(セント単位で丸め)のどちらかを受け取ります。任意の金額は、パックと同じ一律のレートで換算されます。両方を送った場合はpackage_idが優先され、価格とクレジットはカタログから決まります。不明なpackage_idはinvalid_packageコード付きのHTTP 400を、範囲外の金額はinvalid_amountを返します。同時に開いておける決済は最大5件で、それ以上はいずれかが支払い済み、キャンセル、期限切れになるまでHTTP 429を返します。レスポンスはcheckout_url付きの支払い記録です。支払う人をこのURLに誘導すると、決済パートナーの安全なページで、カード(VisaまたはMastercard)を使ってUSDで支払えます。支払いが確認されると、クレジットは自動的に追加されます。ステータスはGET /v1/billing/payments/{id}でポーリングします。POST /v1/billing/payments/{id}/cancelは、未完了の支払いをキャンセル済みとしてマークします。それでも支払いが完了した場合、クレジットは追加されます。省略可能なproviderフィールドで、支払いを受け付ける決済サービスを選べます。指定できる値はwhop(カード)、nowpayments(暗号資産)、telegram_stars(Telegramスター)です。GET /v1/billing/packagesはprovidersに現在決済に使える決済サービスを列挙し、フィールドを省略した場合は最初のものが使われます。不明または停止中の決済サービスはinvalid_providerコード付きのHTTP 400を返し、providersが空の場合は現在支払いを受け付けていません。各パックは、そのパックに使えない決済サービスをexcluded_providersに列挙します。たとえば、Telegramスターの支払い上限を超えるパックではtelegram_starsです。除外された決済サービスでそのパックの決済を開くと、package_unavailable_for_providerコード付きのHTTP 400が返り、支払いは作成されません。GET /v1/billing/balanceは、使用できる合計のcreditsとその内訳を返します。permanent_credits(購入分)は期限がなく、subscription_creditsはsubscription_expires_at(ミリ秒のタイムスタンプ。有効なサブスクリプションクレジットがない場合はnull)に失効し、gift_credits(新規登録時に1回だけ付与される特典)はgift_expires_at(有効な特典がない場合はnull)に失効します。消費は特典クレジット、サブスクリプションクレジット、購入分のクレジットの順です。月額のサブスクリプションプランはGET /v1/billing/packagesのplansに別に列挙され、各プランにはid、表示名、月額のusd価格、期間ごとに付与されるクレジット数があります。POST /v1/billing/subscribeはその一覧のplan_idを受け取り、保留中のサブスクリプションと、支払う人を誘導するcheckout_urlを返します。サブスクリプションの支払いはカードのみです。whop以外のproviderはinvalid_providerコード付きのHTTP 400を、不明なplan_idはinvalid_planを返します。支払い済みの期間が始まるたびに、残りのサブスクリプションクレジットはプランの全量に置き換わります。使わなかったサブスクリプションクレジットは繰り越されず、購入分のクレジットには一切影響しません。すでに契約中のプランを申し込むと、already_subscribed付きのHTTP 409が返ります。上位プランへの変更はすぐに開始され、現在のプランの残りクレジットが新しい期間に加算されます。下位プランへの変更は、downgrade_requires_cancel付きのHTTP 409を返します。GET /v1/billing/subscriptionは、有効なサブスクリプションをsubscription(plan_id、status、current_period_end、cancel_at_period_end)に、未完了の決済をpendingに返します。どちらもない場合はnullです。同時に開いておける決済は1件だけです。同じプランに再度申し込むと開いている決済が返り、別のプランを選ぶと先に開いている決済が閉じられます。決済ページの作成中に再度申し込むと、checkout_in_progress付きのHTTP 409を返します。POST /v1/billing/subscription/cancelは、現在の期間の終わりで更新を停止します。サブスクリプションクレジットはcurrent_period_endまで使え、返金はありません。cancel_at_period_endがtrueになったサブスクリプションを返し(再度呼び出しても同じ結果です)、有効なサブスクリプションがない場合はsubscription_not_found付きのHTTP 404を、解約を確認できなかった場合はsubscription_cancel_failed付きのHTTP 502を返します。その場合は再度お試しください。plansの各プランにはrankもあります。rankが高いプランは低いプランに対するアップグレードなので、変更の方向は価格ではなくrankで判断します。GET /v1/billing/historyは、サブスクリプションの支払いをsubscription_payments(type subscription、payment_id、subscription_id、plan_id、amount_usd、status(paid、refunded、mismatch)、period_end、created_at)に別に列挙し、subscription_payments_offsetで独立してページングし、件数をsubscription_payments_totalで返します。

GET/v1/billing/balance

使用できるクレジットを、購入分、サブスクリプション分、特典の内訳とともに返します。
curl
curl https://vellria.com/v1/billing/balance \
  -H "Authorization: Bearer vll_..."
#

GET/v1/billing/packages

クレジットパック、任意の金額の範囲、現在使える決済サービス、サブスクリプションプランを返します。公開エンドポイントです。
curl
curl https://vellria.com/v1/billing/packages
#

POST/v1/billing/create-checkout

パックまたは任意の金額でホスティング型の決済ページを開き、支払う人をcheckout_urlに誘導します。

パラメーター

パラメーター説明
package_idstring · ボディ任意GET /v1/billing/packagesのパックID。price_amountも送った場合は、こちらが優先されます。
price_amountnumber · ボディ任意min_usd〜max_usdの範囲の任意の金額(USD、セント単位で丸め)。
providerstring · ボディ任意GET /v1/billing/packagesのprovidersのいずれか。省略時は最初のものが使われます。
curl
curl https://vellria.com/v1/billing/create-checkout \
  -H "Authorization: Bearer vll_..." \
  -H "Content-Type: application/json" \
  -d '{ "package_id": "pack_30", "provider": "whop" }'
curl
curl https://vellria.com/v1/billing/create-checkout \
  -H "Authorization: Bearer vll_..." \
  -H "Content-Type: application/json" \
  -d '{ "price_amount": 25 }'
#

GET/v1/billing/payments/{id}

支払いとそのステータスを取得します。支払いが確認されるとクレジットが追加されます。

パラメーター

パラメーター説明
idstring · パス必須支払いID。
curl
curl https://vellria.com/v1/billing/payments/{id} \
  -H "Authorization: Bearer vll_..."
#

POST/v1/billing/payments/{id}/cancel

未完了の支払いをキャンセル済みとしてマークします。それでも支払われた場合、クレジットは追加されます。

パラメーター

パラメーター説明
idstring · パス必須支払いID。
curl
curl -X POST https://vellria.com/v1/billing/payments/{id}/cancel \
  -H "Authorization: Bearer vll_..."
#

GET/v1/billing/history

支払い、課金された生成、サブスクリプションの支払いを、それぞれ独立したページングで返します。

パラメーター

パラメーター説明
limitinteger · クエリ任意ページサイズ。1〜50(デフォルト20)。
payments_offsetinteger · クエリ任意支払い一覧のみに適用するオフセット。
generations_offsetinteger · クエリ任意生成一覧のみに適用するオフセット。
subscription_payments_offsetinteger · クエリ任意サブスクリプション支払い一覧のみに適用するオフセット。
curl
curl "https://vellria.com/v1/billing/history?limit=20" \
  -H "Authorization: Bearer vll_..."
#

GET/v1/chat/usage

チャットのリクエストを新しい順に返します。送信元、トークン数、端数を含むクレジット費用とそのUSD換算額に加え、まだ残高から差し引かれていない累計費用が含まれます。

パラメーター

パラメーター説明
limitinteger · クエリ任意ページサイズ。1〜50(デフォルト20)。
offsetinteger · クエリ任意スキップする行数。
curl
curl "https://vellria.com/v1/chat/usage?limit=20" \
  -H "Authorization: Bearer vll_..."
#

POST/v1/billing/subscribe

月額プランの決済ページを開きます。カードのみです。

パラメーター

パラメーター説明
plan_idstring · ボディ必須GET /v1/billing/packagesのplansにあるプランID。
providerstring · ボディ任意カードのみ(whop)。それ以外の値はinvalid_providerを返します。
curl
curl https://vellria.com/v1/billing/subscribe \
  -H "Authorization: Bearer vll_..." \
  -H "Content-Type: application/json" \
  -d '{ "plan_id": "starter" }'
#

GET/v1/billing/subscription

有効なサブスクリプションと、開いているサブスクリプションの決済を返します。
curl
curl https://vellria.com/v1/billing/subscription \
  -H "Authorization: Bearer vll_..."
#

POST/v1/billing/subscription/cancel

現在の期間の終わりで更新を停止します。返金はありません。
curl
curl -X POST https://vellria.com/v1/billing/subscription/cancel \
  -H "Authorization: Bearer vll_..."
#

保存期間

#

生成ファイルは7日間保存され、その後サーバーから削除されます。記録は支払い履歴に残りますが、ファイルにはアクセスできなくなります。GET /v1/generationsのレスポンスにはretention_daysフィールドがあり、各生成にはexpires_atがあります。期限切れのファイルをリクエストすると、content_expiredコード付きのHTTP 410が返ります。長く残したいファイルは、あらかじめダウンロードしておいてください。生成を自分で削除することもできます。DELETE /v1/generations/{id}は保存済みのファイルをすぐに削除し、purged_atを返します。削除した生成はAPIから消えます。GET /v1/generationsには表示されなくなり、GET /v1/generations/{id}、そのファイルエンドポイント、2回目のDELETEは、存在しないIDと同じくnot_foundコード付きのHTTP 404を返します。消費したクレジットは返還されず、GET /v1/billing/historyに残ります。失敗した生成の記録は30日後に削除され、以降はGET /v1/generations/{id}とそのファイルエンドポイントがHTTP 404を返します。queuedまたはprocessingの生成はまだ削除できず、generation_in_progressコード付きのHTTP 409を返します。

DELETE/v1/generations/{id}

生成をすぐに削除します。ファイルが削除され、記録はAPIから消えます(404)。消費したクレジットは支払い履歴に残ります。

パラメーター

パラメーター説明
idstring · パス必須生成ID。
curl
curl -X DELETE https://vellria.com/v1/generations/{id} \
  -H "Authorization: Bearer vll_..."
#

アカウントの削除

#

アカウントを削除すると、生成とその保存ファイル、アップロード、APIキー、サポートへのお問い合わせが削除され、ログアウトされます。アカウントに残っているクレジットは失われ、返金されません。支払い記録は取引記録として保持されるため、削除したアカウントも、保存が義務付けられている支払い履歴には残ります。このエンドポイントはセッションでのみ認証されます。マイページのアカウントページから呼び出され、APIキーを含むリクエストはHTTP 403で拒否されます。支払いがまだ確定していないアカウントは、その支払いがクレジットとして反映される可能性があるため削除できず、pending_paymentコード付きのHTTP 409を返します。アカウントを別のアカウントに連携している間も、同じHTTP 409がmerge_in_progressで返ります。どちらの場合も、少し待ってから再度お試しください。

DELETE/v1/account

アカウントを削除します。セッション専用で、マイページから呼び出されます。APIキーでは拒否されます。
#

コンテンツポリシー

#

APIキーで行うリクエストは、送られたとおりにモデルへ渡されます。promptとnegative_promptはバイト単位でそのまま生成サービスに届き、モデルが設定として備えるプロンプトの書き換え機能はオフにして送信されます(一部の動画モデルは組み込みの思考ステップを維持します)。アプリケーション側でのコンテンツ管理は、開発者の責任で行ってください。

詳細
  • APIに残るチェックは1つだけです。未成年者への性的虐待に関わるリクエストは、クレジットが差し引かれる前にHTTP 400とcontent_blockedで拒否されます(チェックが一時的に利用できない場合はRetry-After付きのHTTP 503)。参照画像を含め、それ以外はチェックされません。ただし利用規約では、獣姦、血縁者間の近親相姦、同意のない性行為、過度な暴力やグロテスクな表現、盗撮コンテンツ、実在の人物を同意なく描写することを引き続き禁止しています。未成年者と同意のない性行為に関する2つのルールには一切の例外がなく、違反した場合は予告なくアカウントが閉鎖されます。Vellriaのマイページから送られたプロンプトも、自動的にチェックされます。
  • モデルを実行する生成サービスは独自の安全フィルターを適用しており、開始後にリクエストを拒否することがあります。その場合、生成は失敗となり、開始時に差し引かれたクレジットは自動的に返還されます。