Create an App Run

POST/openapi/v1/app-runs

POST /openapi/v1/app-runs
Authorization: Bearer <API_KEY>
Content-Type: application/json

Request parameters

Parameter	Location	Type	Required	Description
`appId`	Body	`string`	Yes	App ID
`projectId`	Body	`string`	Yes	Project ID; determines result ownership and the project charged
`inputJson`	Body	`object`	Yes	Map from the App's declared input keys to input values

Use List published Apps to obtain an App ID in the project, then call Get App details before creating a Run. inputJson must follow the current data.inputs returned by App details.

Request body example

{

"appId": "REPLACE_WITH_YOUR_APP_ID",

"projectId": "REPLACE_WITH_YOUR_PROJECT_ID",

"inputJson": {

"outfit_prompt": "Fashion outfit flat lay on white background",

"character_image": {

"url": "https://example.com/a.png"

}

stringRequired; App ID

stringRequired; Project ID that determines result ownership and the project charged

objectRequired; map from the App's declared input keys to input values

stringText input for the example App; actual fields must follow data.inputs returned by App details

objectImage input object for the example App

stringAbsolute HTTPS media URL directly accessible to the execution service

The request body accepts only these three top-level fields. Additional top-level fields return INVALID_REQUEST.

inputJson rules

Each App's publisher defines its input keys, types, required status, and defaults. Clients may send only declared keys.

Text input example

{

"prompt": "A cinematic product shot"

}

stringText input value declared by the App

Media input example

{

"reference_image": {

"url": "https://example.com/a.png"

}

objectImage, video, or audio input object declared by the App

stringAbsolute HTTPS media URL directly accessible to the execution service

A media object must contain exactly one url field. The media URL must:

Be an absolute HTTPS URL;
Contain no username, password, or URL fragment;
Be accessible during the Run without browser sign-in, Cookies, or interaction;
Not point to localhost, private networks, link-local networks, CGNAT, reserved ranges, or cloud metadata addresses;
Be downloadable by the execution service within a reasonable time.

Direct binary uploads, Base64, data: URLs, HTTP URLs, other resource IDs, and additional media object fields such as a filename are not supported.

The API returns APP_INPUT_INVALID when:

An undeclared key is supplied;
A required input without a default is missing;
A text input is not a string;
A media input is not { "url": "https://..." };
A URL cannot be parsed or violates the security rules.

Creation semantics and billing

When the server accepts the request, it locks the App's current published version. Taking the App offline or republishing it later does not affect Runs that were already created successfully.

The success status is HTTP 201.

Success response example

{

"code": 200,

"message": "success",

"data": {

"runId": "e8f4c7a135d64211a8d2c0019b57ef63",

"estimatedPrice": "12.50000000"

}

integerProtocol field, currently fixed at 200

stringFixed at success on success

objectNewly created Run

stringNew Run ID used to query status and results

decimal stringEstimated Credit price for this Run, with exactly 8 decimal places

estimatedPrice is used for the pre-Run balance check and display. It is not a final price or price cap. Both the balance check and actual charges belong to the project identified by projectId; actualPrice reflects the charges actually incurred. Every POST creates a new Run.

Code examples

First update inputJson to match the data.inputs returned by App details. The examples below use the MAXDAY_API_KEY environment variable.

curl --fail-with-body --request POST \
  "https://api.maxday.ai/bio/dramas/v1/openapi/v1/app-runs" \
  --header "Authorization: Bearer ${MAXDAY_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "appId": "REPLACE_WITH_YOUR_APP_ID",
    "projectId": "REPLACE_WITH_YOUR_PROJECT_ID",
    "inputJson": {
      "outfit_prompt": "Fashion outfit flat lay on white background",
      "character_image": {"url": "https://example.com/a.png"}
    }
  }'

const response = await fetch("https://api.maxday.ai/bio/dramas/v1/openapi/v1/app-runs", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MAXDAY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    appId: "REPLACE_WITH_YOUR_APP_ID",
    projectId: "REPLACE_WITH_YOUR_PROJECT_ID",
    inputJson: {
      outfit_prompt: "Fashion outfit flat lay on white background",
      character_image: { url: "https://example.com/a.png" },
    },
  }),
});
const body = await response.json();

if (!response.ok || body.message !== "success") {
  throw new Error(body.data?.error?.message || body.message || `HTTP ${response.status}`);
}
console.log(body.data);

import json
import os
from urllib.request import Request, urlopen

payload = {
    "appId": "REPLACE_WITH_YOUR_APP_ID",
    "projectId": "REPLACE_WITH_YOUR_PROJECT_ID",
    "inputJson": {
        "outfit_prompt": "Fashion outfit flat lay on white background",
        "character_image": {"url": "https://example.com/a.png"},
    },
}
request = Request(
    "https://api.maxday.ai/bio/dramas/v1/openapi/v1/app-runs",
    data=json.dumps(payload).encode("utf-8"),
    method="POST",
    headers={
        "Authorization": "Bearer " + os.environ["MAXDAY_API_KEY"],
        "Content-Type": "application/json",
    },
)

with urlopen(request, timeout=60) as response:
    body = json.load(response)

if body.get("message") != "success":
    error = body.get("data", {}).get("error", {})
    raise RuntimeError(error.get("message") or body.get("message"))
print(json.dumps(body["data"], ensure_ascii=False, indent=2))

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Map;

public final class CreateAppRunExample {
  public static void main(String[] args) throws Exception {
    ObjectMapper json = new ObjectMapper();
    Map<String, Object> payload = Map.of(
        "appId", "REPLACE_WITH_YOUR_APP_ID",
        "projectId", "REPLACE_WITH_YOUR_PROJECT_ID",
        "inputJson", Map.of(
            "outfit_prompt", "Fashion outfit flat lay on white background",
            "character_image", Map.of("url", "https://example.com/a.png")
        )
    );
    HttpRequest request = HttpRequest.newBuilder(
            URI.create("https://api.maxday.ai/bio/dramas/v1/openapi/v1/app-runs"))
        .header("Authorization", "Bearer " + System.getenv("MAXDAY_API_KEY"))
        .header("Content-Type", "application/json")
        .POST(HttpRequest.BodyPublishers.ofString(json.writeValueAsString(payload)))
        .build();
    HttpResponse<String> response = HttpClient.newHttpClient().send(
        request,
        HttpResponse.BodyHandlers.ofString()
    );
    JsonNode body = json.readTree(response.body());

    if (response.statusCode() < 200 || response.statusCode() >= 300
        || !"success".equals(body.path("message").asText())) {
      throw new IllegalStateException(
          body.path("data").path("error").path("message").asText(
              body.path("message").asText("HTTP " + response.statusCode())
          )
      );
    }
    System.out.println(body.path("data").toPrettyString());
  }
}