HTTP API

Authentication

All API requests require a valid API token in the Authorization header. The token should be prefixed with "Bearer", followed by a space and the token itself. Example:

Authorization: Bearer Hw***********************************

You can find your API tokens at https://vaikerai.com/account/api-tokens.

Retrieve Authenticated Account

Endpoint: GET https://api.vaikerai.com/v1/account

Description: This endpoint returns details about the user or organization associated with the provided API token.

Example cURL Request:

curl -s \
  -H "Authorization: Bearer <your-token-here>" \
  https://api.vaikerai.com/v1/account

Response Example:

{
  "type": "organization",
  "username": "acme",
  "name": "Acme Corp, Inc.",
  "github_url": "https://github.com/acme"
}

List Model Collections

Endpoint: GET https://api.vaikerai.com/v1/collections

Description: This endpoint returns a paginated list of model collections.

Example cURL Request:

curl -s \
  -H "Authorization: Bearer <your-token-here>" \
  https://api.vaikerai.com/v1/collections

Response Example:

{
  "next": null,
  "previous": null,
  "results": [
    {
      "name": "Super resolution",
      "slug": "super-resolution",
      "description": "Upscaling models that create high-quality images from low-quality images."
    }
  ]
}

Retrieve a Model Collection

Endpoint: GET https://api.vaikerai.com/v1/collections/{collection_slug}

Description: Fetches details of a specific model collection, including the models within it.

Example cURL Request:

curl -s \
  -H "Authorization: Bearer <your-token-here>" \
  https://api.vaikerai.com/v1/collections/super-resolution

Response Example:

{
  "name": "Super resolution",
  "slug": "super-resolution",
  "description": "Upscaling models that create high-quality images from low-quality images.",
  "models": [...]
}

Parameters:

  • collection_slug (string, required): The slug identifier for the collection (e.g., super-resolution, image-restoration).

List Deployments

Endpoint: GET https://api.vaikerai.com/v1/deployments

Description: Retrieves a list of deployments associated with the current account, including their latest release configurations.

Example cURL Request:

curl -s \
  -H "Authorization: Bearer <your-token-here>" \
  https://api.vaikerai.com/v1/deployments

Response Example:

{
  "next": "https://api.vaikerai.com/v1/deployments?cursor=...",
  "previous": null,
  "results": [
    {
      "owner": "vaikerai",
      "name": "my-app-image-generator",
      "current_release": {
        "number": 1,
        "model": "stability-ai/sdxl",
        "version": "da77bc59ee60423279fd632efb4795ab731d9e3ca9705ef3341091fb989b7eaf",
        "created_at": "2024-02-15T16:32:57.018467Z",
        "created_by": {
          "type": "organization",
          "username": "acme",
          "name": "Acme Corp, Inc.",
          "github_url": "https://github.com/acme"
        },
        "configuration": {
          "hardware": "gpu-t4",
          "min_instances": 1,
          "max_instances": 5
        }
      }
    }
  ]
}

Create a Deployment

Endpoint: POST https://api.vaikerai.com/v1/deployments

Description: Creates a new deployment.

Example cURL Request:

curl -s \
  -X POST \
  -H "Authorization: Bearer <your-token-here>" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "my-app-image-generator",
        "model": "stability-ai/sdxl",
        "version": "da77bc59ee60423279fd632efb4795ab731d9e3ca9705ef3341091fb989b7eaf",
        "hardware": "gpu-t4",
        "min_instances": 0,
        "max_instances": 3
      }' \
  https://api.vaikerai.com/v1/deployments

Response Example:

{
  "owner": "acme",
  "name": "my-app-image-generator",
  "current_release": {
    "number": 1,
    "model": "stability-ai/sdxl",
    "version": "da77bc59ee60423279fd632efb4795ab731d9e3ca9705ef3341091fb989b7eaf",
    "created_at": "2024-02-15T16:32:57.018467Z",
    "created_by": {
      "type": "organization",
      "username": "acme",
      "name": "Acme Corp, Inc.",
      "github_url": "https://github.com/acme"
    },
    "configuration": {
      "hardware": "gpu-t4",
      "min_instances": 1,
      "max_instances": 5
    }
  }
}

Request Body Parameters:

  • hardware (string, required): SKU for the hardware used to run the model. Retrieve options from the hardware.list endpoint.

  • max_instances (integer, required): Maximum number of instances for scaling.

  • min_instances (integer, required): Minimum number of instances for scaling.

  • model (string, required): Full name of the model to deploy (e.g., stability-ai/sdxl).

  • name (string, required): Name of the deployment.

  • version (string, required): 64-character ID of the model version to deploy.

Delete a Deployment

Endpoint: DELETE https://api.vaikerai.com/v1/deployments/{deployment_owner}/{deployment_name}

Description: Deletes a specified deployment. Note that deployments can only be deleted if they have been offline and unused for at least 15 minutes.

Example cURL Request:

curl -s -X DELETE \
  -H "Authorization: Bearer <your-token-here>" \
  https://api.vaikerai.com/v1/deployments/acme/my-app-image-generator

Response: An empty response with HTTP status 204 indicates successful deletion.

Parameters:

  • deployment_owner (string, required): The name of the user or organization that owns the deployment.

  • deployment_name (string, required): The name of the deployment.

Retrieve a Deployment

Endpoint: GET https://api.vaikerai.com/v1/deployments/{deployment_owner}/{deployment_name}

Description: Fetches details about a specific deployment, including its current release.

Example cURL Request:

curl -s \
  -H "Authorization: Bearer <your-token-here>" \
  https://api.vaikerai.com/v1/deployments/vaikerai/my-app-image-generator

Response Example:

{
  "owner": "acme",
  "name": "my-app-image-generator",
  "current_release": {
    "number": 1,
    "model": "stability-ai/sdxl",
    "version": "da77bc59ee60423279fd632efb4795ab731d9e3ca9705ef3341091fb989b7eaf",
    "created_at": "2024-02-15T16:32:57.018467Z",
    "created_by": {
      "type": "organization",
      "username": "acme",
      "name": "Acme Corp, Inc.",
      "github_url": "https://github.com/acme"
    },
    "configuration": {
      "hardware": "gpu-t4",
      "min_instances": 1,
      "max_instances": 5
    }
  }
}

Parameters:

  • deployment_owner (string, required): The name of the user or organization that owns the deployment.

  • deployment_name (string, required): The name of the deployment.

Update a Deployment

Endpoint

PATCH https://api.vaikerai.com/v1/deployments/{deployment_owner}/{deployment_name}

Description

This endpoint allows you to update the properties of an existing deployment. You can modify hardware settings, adjust the minimum and maximum instances, and change the deployment's underlying model version.

Example cURL Request:

curl -s \
  -X PATCH \
  -H "Authorization: Bearer <paste-your-token-here>" \
  -H "Content-Type: application/json" \
  -d '{"min_instances": 3, "max_instances": 10}' \
  https://api.vaikerai.com/v1/deployments/acme/my-app-image-generator

Example JSON Response:

{
  "owner": "acme",
  "name": "my-app-image-generator",
  "current_release": {
    "number": 2,
    "model": "stability-ai/sdxl",
    "version": "da77bc59ee60423279fd632efb4795ab731d9e3ca9705ef3341091fb989b7eaf",
    "created_at": "2024-02-15T16:32:57.018467Z",
    "created_by": {
      "type": "organization",
      "username": "acme",
      "name": "Acme Corp, Inc.",
      "github_url": "https://github.com/acme"
    },
    "configuration": {
      "hardware": "gpu-t4",
      "min_instances": 3,
      "max_instances": 10
    }
  }
}

Updating any deployment property will increment the number field of the current_release.

Parameters

  • deployment_owner (string, required): The username or organization name that owns the deployment.

  • deployment_name (string, required): The name of the deployment to be updated.

Request Body

  • hardware (string, optional): The SKU of the hardware used to run the model. Possible values can be retrieved from the hardware.list endpoint.

  • max_instances (integer, optional): The maximum number of instances for scaling.

  • min_instances (integer, optional): The minimum number of instances for scaling.

  • version (string, optional): The ID of the model version to deploy.

Create a Prediction Using a Deployment

Endpoint

POST https://api.vaikerai.com/v1/deployments/{deployment_owner}/{deployment_name}/predictions

Description

This endpoint starts a new prediction using the specified deployment. Provide the required input to initiate the prediction process.

Example Request Body:

{
  "input": {
    "text": "Alice"
  }
}

Example cURL Request:

curl -s -X POST \
  -d '{"input": {"text": "Alice"}}' \
  -H "Authorization: Bearer <paste-your-token-here>" \
  -H "Content-Type: application/json" \
  "https://api.vaikerai.com/v1/deployments/vaikerai/hello-world/predictions"

Example JSON Response:

{
  "id": "86b6trbv99rgp0cf1h886f69ew",
  "model": "vaikerai/hello-world",
  "version": "dp-8e43d61c333b5ddc7a921130bc3ab3ea",
  "input": {
    "text": "Alice"
  },
  "logs": "",
  "error": null,
  "status": "starting",
  "created_at": "2024-04-23T18:55:52.138Z",
  "urls": {
    "cancel": "https://api.vaikerai.com/v1/predictions/86b6trbv99rgp0cf1h886f69ew/cancel",
    "get": "https://api.vaikerai.com/v1/predictions/86b6trbv99rgp0cf1h886f69ew"
  }
}

Note: Predictions may take several seconds or more to process. To obtain the final result, either provide a webhook URL for notifications or poll the "Get a Prediction" endpoint until the process completes.

Input and output data, including any files, are automatically deleted after one hour. Ensure you save any output files if you intend to use them later.

Output files are served by files.vaikerai.com and its subdomains. If you use an allowlist of external domains, make sure to add files.vaikerai.com to it.

Parameters

  • deployment_owner (string, required): The username or organization name that owns the deployment.

  • deployment_name (string, required): The name of the deployment to use for the prediction.

Request Body

  • input (object, required): The input for the model as a JSON object. The input schema depends on the model being used. To see available inputs, refer to the "API" tab on the model’s page or retrieve the model version and check the openapi_schema property.

    • Use an HTTP URL for files larger than 256 KB, files you plan to reuse, or to associate metadata with your input files.

    • Use a Data URL for files smaller than 256 KB, files that don't need to be hosted, or files you don't need to reuse (VaikerAI will not store them).

  • stream (boolean, deprecated): This field is no longer required. The returned prediction will automatically include a stream entry in its url property if streaming is supported by the model.

  • webhook (string, optional): An HTTPS URL to receive a POST request when the prediction generates new output. The request body mirrors the response body of the "Get a Prediction" operation. If network issues occur, the webhook will retry a few times, so it must handle multiple calls without issues. VaikerAI does not follow redirects, so provide a URL that resolves directly.

  • webhook_events_filter (array, optional): Customize which events trigger webhook notifications. Available options:

    • start: Triggered when the prediction starts.

    • output: Triggered whenever new output is generated (multiple outputs possible).

    • logs: Triggered when logs are generated.

    • completed: Triggered when the prediction finishes (succeeded/canceled/failed).

    Example: To receive notifications only at the start and end of the prediction:

    {
  "input": {
    "text": "Alice"
  },
  "webhook": "https://example.com/my-webhook",
  "webhook_events_filter": ["start", "completed"]
}

    Note: output and logs events are sent at most once every 500ms. start and completed events will always be sent, regardless of throttling.

List Available Hardware for Models

Endpoint

GET https://api.vaikerai.com/v1/hardware

Description

Retrieve a list of available hardware configurations that can be used for running models.

Example cURL Request:

curl -s \
  -H "Authorization: Bearer <paste-your-token-here>" \
  https://api.vaikerai.com/v1/hardware

Example JSON Response:

[
  {"name": "CPU", "sku": "cpu"},
  {"name": "Nvidia T4 GPU", "sku": "gpu-t4"},
  {"name": "Nvidia A40 GPU", "sku": "gpu-a40-small"},
  {"name": "Nvidia A40 (Large) GPU", "sku": "gpu-a40-large"}
]

List Public Models

Endpoint

GET https://api.vaikerai.com/v1/models

Description

Retrieve a paginated list of publicly available models.

Example cURL Request:

curl -s \
  -H "Authorization: Bearer <paste-your-token-here>" \
  https://api.vaikerai.com/v1/models

Example JSON Response:

{
  "next": null,
  "previous": null,
  "results": [
    {
      "url": "https://vaikerai.com/acme/hello-world",
      "owner": "acme",
      "name": "hello-world",
      "description": "A tiny model that says hello",
      "visibility": "public",
      "github_url": "https://github.com/vaikerai/examples",
      "paper_url": null,
      "license_url": null,
      "run_count": 5681081,
      "cover_image_url": "...",
      "default_example": {...},
      "latest_version": {...}
    }
  ]
}

Note: The cover_image_url is an HTTPS URL pointing to an image file. This can be:

  • An image uploaded by the model author.

  • The output file of the example prediction (if the author hasn’t set a cover image).

  • The input file of the example prediction (if neither the author sets a cover image nor the example prediction has an output file).

  • A generic fallback image.

Create a Model

Endpoint

POST https://api.vaikerai.com/v1/models

Description

Create a new model within your account.

Example cURL Request:

curl -s -X POST \
  -H "Authorization: Bearer <paste-your-token-here>" \
  -H "Content-Type: application/json" \
  -d '{"owner": "alice", "name": "my-model", "description": "An example model", "visibility": "public", "hardware": "cpu"}' \
  https://api.vaikerai.com/v1/models

Example JSON Response:

{
  "url": "https://vaikerai.com/alice/my-model",
  "owner": "alice",
  "name": "my-model",
  "description": "An example model",
  "visibility": "public",
  "github_url": null,
  "paper_url": null,
  "license_url": null,
  "run_count": 0,
  "cover_image_url": null,
  "default_example": null,
  "latest_version": null
}

Note: There is a limit of 1,000 models per account. We recommend using a single model and pushing new versions as needed.

Request Body

  • cover_image_url (string, optional): URL of the model's cover image (must be an image file).

  • description (string, optional): A description of the model.

  • github_url (string, optional): URL to the model's source code repository on GitHub.

  • hardware (string, required): The SKU of the hardware used to run the model. Possible values can be retrieved from the hardware.list endpoint.

  • license_url (string, optional): URL of the model's license.

  • name (string, required): The name of the model. Must be unique among all models owned by the user or organization.

  • owner (string, required): The name of the user or organization that will own the model. This must match the user or organization associated with the API token used in the request.

  • paper_url (string, optional): URL of the model's associated paper (if any).

  • visibility (string, required): Determines whether the model should be public or private. Public models are accessible to everyone, while private models can only be viewed and run by the owner or organization members.

Search Public Models

Endpoint

POST https://api.vaikerai.com/v1/models/search

Description

Retrieve a list of public models that match a specific search query.

Example cURL Request:

curl -s -X POST \
  -H "Authorization: Bearer <paste-your-token-here>" \
  -H "Content-Type: text/plain" \
  -d "hello" \
  https://api.vaikerai.com/v1/models/search

Example JSON Response:

{
  "next": null,
  "previous": null,
  "results": [
    {
      "url": "https://vaikerai.com/acme/hello-world",
      "owner": "acme",
      "name": "hello-world",
      "description": "A tiny model that says hello",
      "visibility": "public",
      "github_url": "https://github.com/vaikerai/examples",
      "paper_url": null,
      "license_url": null,
      "run_count": 5681081,
      "cover_image_url": "...",
      "default_example": {...},
      "latest_version": {...}
    }
  ]
}

Note: The cover_image_url is an HTTPS URL for an image file. It may be:

  • An image uploaded by the model author.

  • The output of an example prediction if no cover image was set.

  • The input of an example prediction if neither a cover image nor output file was set.

  • A generic fallback image.

Delete a Model

Endpoint

DELETE https://api.vaikerai.com/v1/models/{model_owner}/{model_name}

Description

Delete a specific model. Note that model deletion is subject to the following restrictions:

  • You can only delete models you own.

  • Only private models can be deleted.

  • Models with associated versions cannot be deleted until all versions are removed.

Example cURL Request:

curl -s -X DELETE \
  -H "Authorization: Bearer <paste-your-token-here>" \
  https://api.vaikerai.com/v1/models/vaikerai/hello-world

Example Response:

A successful deletion will return a 204 No Content response, indicating the model has been removed.

Parameters

  • model_owner (string, required): The name of the user or organization that owns the model.

  • model_name (string, required): The name of the model.

Get a Model

Endpoint

GET https://api.vaikerai.com/v1/models/{model_owner}/{model_name}

Description

Retrieve detailed information about a specific model.

Example cURL Request:

curl -s \
  -H "Authorization: Bearer <paste-your-token-here>" \
  https://api.vaikerai.com/v1/models/vaikerai/hello-world

Example JSON Response:

{
  "url": "https://vaikerai.com/vaikerai/hello-world",
  "owner": "vaikerai",
  "name": "hello-world",
  "description": "A tiny model that says hello",
  "visibility": "public",
  "github_url": "https://github.com/vaikerai/cog-examples",
  "paper_url": null,
  "license_url": null,
  "run_count": 5681081,
  "cover_image_url": "...",
  "default_example": {...},
  "latest_version": {...}
}

Note: The cover_image_url is an HTTPS URL pointing to an image file. It can be:

  • An image uploaded by the model author.

  • The output of the example prediction if no cover image is set.

  • The input of the example prediction if there is no cover image or output file.

  • A generic fallback image.

The default_example is a prediction created with this model.

The latest_version is the most recent version of the model that was pushed.

Parameters

  • model_owner (string, required): The name of the user or organization that owns the model.

  • model_name (string, required): The name of the model.

Create a Prediction Using an Official Model

Endpoint

POST https://api.vaikerai.com/v1/models/{model_owner}/{model_name}/predictions

Description

Initiate a new prediction using an official model by providing the required input parameters.

Example Request Body:

{
  "input": {
    "prompt": "Write a short poem about the weather."
  }
}

Example cURL Request:

curl -s -X POST \
  -d '{"input": {"prompt": "Write a short poem about the weather."}}' \
  -H "Authorization: Bearer <paste-your-token-here>" \
  -H 'Content-Type: application/json' \
  https://api.vaikerai.com/v1/models/meta/meta-llama-3-70b-instruct/predictions

Example JSON Response:

{
  "id": "25s2s4n7rdrgg0cf1httb3myk0",
  "model": "vaikerai-internal/llama3-70b-chat-vllm-unquantized",
  "version": "dp-cf04fe09351e25db628e8b6181276547",
  "input": {
    "prompt": "Write a short poem about the weather."
  },
  "logs": "",
  "error": null,
  "status": "starting",
  "created_at": "2024-04-23T19:36:28.355Z",
  "urls": {
    "cancel": "https://api.vaikerai.com/v1/predictions/25s2s4n7rdrgg0cf1httb3myk0/cancel",
    "get": "https://api.vaikerai.com/v1/predictions/25s2s4n7rdrgg0cf1httb3myk0"
  }
}

Note: Predictions can take several seconds or more to complete. The output is not immediately available. To retrieve the final result, you can either provide a webhook URL for notification or poll the "Get a Prediction" endpoint until the prediction is complete.

All input parameters, output values, and logs are automatically deleted after one hour by default. Output files are served from files.vaikerai.com and its subdomains. If you use an allowlist for external domains, ensure this domain is included.

Parameters

  • model_owner (string, required): The name of the user or organization that owns the model.

  • model_name (string, required): The name of the model.

Request Body

  • input (object, required): The input for the model in JSON format. The input schema depends on the model being used. To view the available inputs, click the "API" tab on the model's page or retrieve the model version and check its openapi_schema property. For example, stability-ai/sdxl accepts prompt as an input.

    Files should be passed as HTTP URLs or data URLs:

    • HTTP URL: Use this when you have a large file (>256 KB), want to reuse the file, or need to associate your prediction metadata with your input files.

    • Data URL: Use this when you have a small file (≤256 KB), do not want to upload and host the file, or do not need to reuse the file (VaikerAI will not store it).

  • stream (boolean, deprecated): This field is deprecated and no longer required. If the model supports streaming, the returned prediction will always have a stream entry in its url property.

  • webhook (string): An HTTPS URL to receive a notification when the prediction has new output. The webhook will be a POST request with the same body as the "Get a Prediction" response. If there are network issues, the webhook will be retried several times, so ensure it can be safely called multiple times. VaikerAI will not follow redirects, so specify a URL that resolves directly.

  • webhook_events_filter (array): By default, requests are sent to your webhook URL when there are new outputs or the prediction is complete. You can customize this by specifying webhook_events_filter:

    • start: Triggered when the prediction starts.

    • output: Triggered each time the prediction generates output (predictions can have multiple outputs).

    • logs: Triggered each time the prediction generates log output.

    • completed: Triggered when the prediction reaches a terminal state (succeeded, canceled, failed).

    Example request to send only start and completion notifications:

    {
  "input": {
    "text": "Alice"
  },
  "webhook": "https://example.com/my-webhook",
  "webhook_events_filter": ["start", "completed"]
}

    For event types output and logs, requests are sent at most once every 500ms. If you request start and completed webhooks, they will always be sent regardless of throttling.

List Model Versions

Endpoint

GET https://api.vaikerai.com/v1/models/{model_owner}/{model_name}/versions

Description

Retrieve a list of all versions of a specific model, sorted with the most recent version first.

Example cURL Request:

curl -s \
  -H "Authorization: Bearer <paste-your-token-here>" \
  https://api.vaikerai.com/v1/models/vaikerai/hello-world/versions

Example JSON Response:

{
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa",
      "created_at": "2022-04-26T19:29:04.418669Z",
      "cog_version": "0.3.0",
      "openapi_schema": { ... }
    }
  ]
}

Parameters

  • model_owner (string, required): The name of the user or organization that owns the model.

  • model_name (string, required): The name of the model.

Delete a Model Version

Endpoint

DELETE https://api.vaikerai.com/v1/models/{model_owner}/{model_name}/versions/{version_id}

Description

Delete a specific version of a model, along with all associated predictions and output files.

Restrictions:

  • You can only delete versions of models that you own.

  • You can only delete versions of private models.

  • You cannot delete a version if someone other than you has run predictions with it.

  • You cannot delete a version if it is being used as the base model for a fine-tune/training.

  • You cannot delete a version if it has an associated deployment.

  • You cannot delete a version if another model version overrides it.

Example cURL Request:

curl -s -X DELETE \
  -H "Authorization: Bearer <paste-your-token-here>" \
  https://api.vaikerai.com/v1/models/vaikerai/hello-world/versions/5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa

Example Response:

An empty 202 status code, indicating that the deletion request has been accepted. The deletion process might take a few minutes to complete.

Parameters

  • model_owner (string, required): The name of the user or organization that owns the model.

  • model_name (string, required): The name of the model.

  • version_id (string, required): The ID of the version.

Get a Model Version

Endpoint

GET https://api.vaikerai.com/v1/models/{model_owner}/{model_name}/versions/{version_id}

Description

Retrieve details about a specific version of a model.

Example cURL Request:

curl -s \
  -H "Authorization: Bearer <paste-your-token-here>" \
  https://api.vaikerai.com/v1/models/vaikerai/hello-world/versions/5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa

Example JSON Response:

{
  "id": "5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa",
  "created_at": "2022-04-26T19:29:04.418669Z",
  "cog_version": "0.3.0",
  "openapi_schema": { ... }
}

The openapi_schema property describes the model's inputs and outputs using OpenAPI Schema Objects.

Example of Input Schema (for vaikerai/hello-world):

{
  "type": "object",
  "title": "Input",
  "required": ["text"],
  "properties": {
    "text": {
      "x-order": 0,
      "type": "string",
      "title": "Text",
      "description": "Text to prefix with 'hello '"
    }
  }
}

Example of Output Schema (for vaikerai/hello-world):

{
  "type": "string",
  "title": "Output"
}

For more details, refer to the documentation on Cog's supported input and output types.

Parameters

  • model_owner (string, required): The name of the user or organization that owns the model.

  • model_name (string, required): The name of the model.

  • version_id (string, required): The ID of the version.

Create a Training

Endpoint

POST https://api.vaikerai.com/v1/models/{model_owner}/{model_name}/versions/{version_id}/trainings

Description

Initiate a new training session for the specified model version.

Example Request Body:

{
  "destination": "{new_owner}/{new_name}",
  "input": {
    "train_data": "https://example.com/my-input-images.zip"
  },
  "webhook": "https://example.com/my-webhook"
}

Example cURL Request:

curl -s -X POST \
  -d '{"destination": "{new_owner}/{new_name}", "input": {"input_images": "https://example.com/my-input-images.zip"}}' \
  -H "Authorization: Bearer <paste-your-token-here>" \
  -H 'Content-Type: application/json' \
  https://api.vaikerai.com/v1/models/stability-ai/sdxl/versions/da77bc59ee60423279fd632efb4795ab731d9e3ca9705ef3341091fb989b7eaf/trainings

Example Response:

{
  "id": "zz4ibbonubfz7carwiefibzgga",
  "model": "stability-ai/sdxl",
  "version": "da77bc59ee60423279fd632efb4795ab731d9e3ca9705ef3341091fb989b7eaf",
  "input": {
    "input_images": "https://example.com/my-input-images.zip"
  },
  "logs": "",
  "error": null,
  "status": "starting",
  "created_at": "2023-09-08T16:32:56.990893084Z",
  "urls": {
    "cancel": "https://api.vaikerai.com/v1/trainings/zz4ibbonubfz7carwiefibzgga/cancel",
    "get": "https://api.vaikerai.com/v1/trainings/zz4ibbonubfz7carwiefibzgga"
  }
}

Important Notes:

Training can take several minutes or more to complete. You can track the status by either:

  • Providing a webhook URL to be notified when training is complete.

  • Polling the "Get a Training" endpoint until the training finishes.

Upon completion, a new model version is created at the specified destination.

Parameters:

  • model_owner (string, required): The user or organization that owns the model.

  • model_name (string, required): The name of the model.

  • version_id (string, required): The ID of the model version to train.

Request Body:

  • destination (string, required): The target model's destination in the format {destination_model_owner}/{destination_model_name}. Must be an existing model owned by the requestor.

  • input (object, required): Contains the inputs required for the model's train() function.

  • webhook (string, optional): HTTPS URL to receive a POST request when the training completes.

  • webhook_events_filter (array, optional): Specify events that trigger webhook notifications:

    • start: When training starts.

    • output: When an output is generated (trainings can produce multiple outputs).

    • logs: When a log is generated.

    • completed: When the training reaches a terminal state (succeeded/canceled/failed).

Example Webhook Filter:

{
  "destination": "my-organization/my-model",
  "input": {
    "text": "Alice"
  },
  "webhook": "https://example.com/my-webhook",
  "webhook_events_filter": ["start", "completed"]
}

List Predictions

Endpoint

GET https://api.vaikerai.com/v1/predictions

Description

Retrieve a paginated list of predictions you have created, either through the API or the website. Returns up to 100 records per page.

Example cURL Request:

curl -s \
  -H "Authorization: Bearer <paste-your-token-here>" \
  https://api.vaikerai.com/v1/predictions

Example JSON Response:

{
  "next": null,
  "previous": null,
  "results": [
    {
      "completed_at": "2023-09-08T16:19:34.791859Z",
      "created_at": "2023-09-08T16:19:34.907244Z",
      "data_removed": false,
      "error": null,
      "id": "gm3qorzdhgbfurvjtvhg6dckhu",
      "input": {
        "text": "Alice"
      },
      "metrics": {
        "predict_time": 0.012683
      },
      "output": "hello Alice",
      "started_at": "2023-09-08T16:19:34.779176Z",
      "source": "api",
      "status": "succeeded",
      "urls": {
        "get": "https://api.vaikerai.com/v1/predictions/gm3qorzdhgbfurvjtvhg6dckhu",
        "cancel": "https://api.vaikerai.com/v1/predictions/gm3qorzdhgbfurvjtvhg6dckhu/cancel"
      },
      "model": "vaikerai/hello-world",
      "version": "5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa"
    }
  ]
}

Response Details:

  • id: Unique identifier for the prediction.

  • source: Indicates how the prediction was created (web or api).

  • status: Current status of the prediction.

  • urls: Contains URLs for further API requests related to the prediction.

  • model: The model identifier in the format {model_owner}/{model_name}.

  • version: The unique ID of the model version used to create the prediction.

  • data_removed: Indicates if the input and output data have been deleted.

Create a Prediction

Endpoint

POST https://api.vaikerai.com/v1/predictions

Description

Initiate a new prediction using the specified model version and input parameters.

Example Request Body:

{
  "version": "5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa",
  "input": {
    "text": "Alice"
  }
}

Example cURL Request:

curl -s -X POST \
  -d '{"version": "5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa", "input": {"text": "Alice"}}' \
  -H "Authorization: Bearer <paste-your-token-here>" \
  -H 'Content-Type: application/json' \
  https://api.vaikerai.com/v1/predictions

Example Response:

{
  "id": "gm3qorzdhgbfurvjtvhg6dckhu",
  "model": "vaikerai/hello-world",
  "version": "5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa",
  "input": {
    "text": "Alice"
  },
  "output": null,
  "logs": "",
  "error": null,
  "status": "starting",
  "created_at": "2023-09-08T16:19:34.765994657Z",
  "urls": {
    "cancel": "https://api.vaikerai.com/v1/predictions/gm3qorzdhgbfurvjtvhg6dckhu/cancel",
    "get": "https://api.vaikerai.com/v1/predictions/gm3qorzdhgbfurvjtvhg6dckhu"
  }
}

Important Notes:

Predictions may take several seconds or longer to complete. To retrieve the final output, either:

  • Provide a webhook URL to be notified when the prediction is ready.

  • Poll the "Get a Prediction" endpoint until the prediction is finished.

Input and output data (including files) are automatically deleted one hour after the prediction is created. If you wish to keep any output files, be sure to save them before they are removed.

Output files are served via files.vaikerai.com and its subdomains. If you maintain an allowlist of domains for your assets, add files.vaikerai.com to it.

Request Body:

  • input (object, required): The model's input parameters, provided as a JSON object. The input schema varies by model. To view available inputs, refer to the "API" tab of the model you are using, or retrieve the model version's openapi_schema property. For example, the model stability-ai/sdxl accepts prompt as an input.

    • Files can be provided as either HTTP URLs or data URLs:

      • HTTP URL: Use for large files (>256kb), files you plan to reuse, or when associating input files with prediction metadata.

      • Data URL: Use for small files (≤256kb), files you don’t need to upload elsewhere, or files you don’t need to store (VaikerAI won’t retain them).

  • stream (boolean, deprecated): This field is no longer needed. The returned prediction will always include a stream entry in the urls property if the model supports streaming.

  • version (string, required): The ID of the model version you want to use.

  • webhook (string, optional): HTTPS URL for receiving a webhook when the prediction has new output. The webhook will be a POST request with the same structure as the response from the "Get a Prediction" operation. If network issues occur, the webhook will retry multiple times, so ensure it can be safely called multiple times. VaikerAI will not follow redirects, so the URL must resolve directly.

  • webhook_events_filter (array, optional): Customize which events trigger webhook notifications. By default, a webhook is triggered for any new output or when the prediction completes. Available events:

    • start: When the prediction starts.

    • output: Each time the prediction generates an output (predictions may generate multiple outputs).

    • logs: Each time a log is generated.

    • completed: When the prediction reaches a terminal state (succeeded/canceled/failed).

Example Webhook Filter:

{
  "version": "5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa",
  "input": {
    "text": "Alice"
  },
  "webhook": "https://example.com/my-webhook",
  "webhook_events_filter": ["start", "completed"]
}

Get a Prediction

Endpoint

GET https://api.vaikerai.com/v1/predictions/{prediction_id}

Description

Retrieve the current status and details of a specific prediction.

Example cURL Request:

curl -s \
  -H "Authorization: Bearer <paste-your-token-here>" \
  https://api.vaikerai.com/v1/predictions/gm3qorzdhgbfurvjtvhg6dckhu

Example Response:

{
  "id": "gm3qorzdhgbfurvjtvhg6dckhu",
  "model": "vaikerai/hello-world",
  "version": "5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa",
  "input": {
    "text": "Alice"
  },
  "logs": "",
  "output": "hello Alice",
  "error": null,
  "status": "succeeded",
  "created_at": "2023-09-08T16:19:34.765994Z",
  "data_removed": false,
  "started_at": "2023-09-08T16:19:34.779176Z",
  "completed_at": "2023-09-08T16:19:34.791859Z",
  "metrics": {
    "predict_time": 0.012683
  },
  "urls": {
    "cancel": "https://api.vaikerai.com/v1/predictions/gm3qorzdhgbfurvjtvhg6dckhu/cancel",
    "get": "https://api.vaikerai.com/v1/predictions/gm3qorzdhgbfurvjtvhg6dckhu"
  }
}

Status Codes:

  • starting: The prediction is starting up. If this status persists for several seconds, it may indicate that a new worker is being initiated.

  • processing: The model's predict() function is currently running.

  • succeeded: The prediction completed successfully.

  • failed: An error occurred during the prediction process.

  • canceled: The prediction was canceled by the user.

Metrics:

  • On successful completion, the metrics object will include predict_time, indicating the CPU or GPU time (in seconds) used by the prediction.

  • All input parameters, output values, and logs are automatically deleted after one hour for API-created predictions. After this, the output key will remain, but its value will be null.

Output files are served via files.vaikerai.com and its subdomains. If you maintain an allowlist of domains for your assets, add files.vaikerai.com to it.

Parameters:

  • prediction_id (string, required): The unique ID of the prediction to retrieve.

Cancel a Prediction

Endpoint

POST https://api.vaikerai.com/v1/predictions/{prediction_id}/cancel

Description

Cancels an ongoing prediction.

Required Parameters

  • prediction_id: The unique identifier of the prediction to cancel.

List Trainings

Endpoint

GET https://api.vaikerai.com/v1/trainings

Description

Retrieves a paginated list of all the trainings you have created, including those created via the API and the website. The response returns up to 100 records per page.

Example cURL Request

curl -s \
  -H "Authorization: Bearer <paste-your-token-here>" \
  https://api.vaikerai.com/v1/trainings

Response Format

The response is a JSON object containing an array of training objects, sorted by the most recent first:

{
  "next": null,
  "previous": null,
  "results": [
    {
      "completed_at": "2023-09-08T16:41:19.826523Z",
      "created_at": "2023-09-08T16:32:57.018467Z",
      "error": null,
      "id": "zz4ibbonubfz7carwiefibzgga",
      "input": {
        "input_images": "https://example.com/my-input-images.zip"
      },
      "metrics": {
        "predict_time": 502.713876
      },
      "output": {
        "version": "...",
        "weights": "..."
      },
      "started_at": "2023-09-08T16:32:57.112647Z",
      "source": "api",
      "status": "succeeded",
      "urls": {
        "get": "https://api.vaikerai.com/v1/trainings/zz4ibbonubfz7carwiefibzgga",
        "cancel": "https://api.vaikerai.com/v1/trainings/zz4ibbonubfz7carwiefibzgga/cancel"
      },
      "model": "stability-ai/sdxl",
      "version": "da77bc59ee60423279fd632efb4795ab731d9e3ca9705ef3341091fb989b7eaf"
    }
  ]
}

Key Fields

  • id: Unique ID of the training.

  • source: Origin of the training (either web or api).

  • status: The current status of the training. Refer to the "Get a Training" section for possible values.

  • urls: Object containing URLs to interact with the training, such as getting the training's details or canceling it.

  • version: The unique ID of the model version used for the training.

Get a Training

Endpoint

GET https://api.vaikerai.com/v1/trainings/{training_id}

Description

Retrieves the current state and details of a specific training.

Example cURL Request

curl -s \
  -H "Authorization: Bearer <paste-your-token-here>" \
  https://api.vaikerai.com/v1/trainings/{training_id}

Response Format

The response is a JSON object containing the training details:

{
  "completed_at": "2023-09-08T16:41:19.826523Z",
  "created_at": "2023-09-08T16:32:57.018467Z",
  "error": null,
  "id": "zz4ibbonubfz7carwiefibzgga",
  "input": {
    "input_images": "https://example.com/my-input-images.zip"
  },
  "logs": "...",
  "metrics": {
    "predict_time": 502.713876
  },
  "output": {
    "version": "...",
    "weights": "..."
  },
  "started_at": "2023-09-08T16:32:57.112647Z",
  "status": "succeeded",
  "urls": {
    "get": "https://api.vaikerai.com/v1/trainings/zz4ibbonubfz7carwiefibzgga",
    "cancel": "https://api.vaikerai.com/v1/trainings/zz4ibbonubfz7carwiefibzgga/cancel"
  },
  "model": "stability-ai/sdxl",
  "version": "da77bc59ee60423279fd632efb4795ab731d9e3ca9705ef3341091fb989b7eaf"
}

Status Values

  • starting: The training is initializing. If this status persists, it might indicate that a new worker is being prepared.

  • processing: The model's train() method is currently executing.

  • succeeded: The training completed successfully.

  • failed: The training encountered an error.

  • canceled: The training was canceled.

In case of success, the output object will contain the results, such as model weights, and any associated files will be available via HTTPS URLs. For failed trainings, the error field will describe the issue.

Metrics such as predict_time will show the processing time (in seconds) consumed by the training.

Cancel a Training

Endpoint

POST https://api.vaikerai.com/v1/trainings/{training_id}/cancel

Description

Cancels an ongoing training.

Required Parameters

  • training_id: The unique identifier of the training to cancel.

Get the Signing Secret for the Default Webhook

Endpoint

GET https://api.vaikerai.com/v1/webhooks/default/secret

Description

Retrieves the signing secret for your default webhook. This secret is used to verify that incoming webhook requests are authentic and sent by VaikerAI.

Example cURL Request

curl -s \
  -H "Authorization: Bearer <paste-your-token-here>" \
  https://api.vaikerai.com/v1/webhooks/default/secret

Response Format

The response is a JSON object containing your secret key:

{
  "key": "..."
}

Rate Limits

VaikerAI imposes rate limits on API usage:

  • Create Prediction: 600 requests per minute.

  • All Other Endpoints: 3000 requests per minute.

If a rate limit is exceeded, you will receive a 429 status response:

{
  "detail": "Request was throttled. Expected available in 1 second."
}

For higher limits, please contact us.

OpenAPI Schema

The OpenAPI (formerly Swagger) specification provides a standardized way to describe HTTP APIs, detailing available endpoints, request/response formats, and other metadata.

You can download VaikerAI's OpenAPI schema at https://api.vaikerai.com/openapi.json.

PreviousClient LibrariesNextFine-tune an Image model

Last updated