Quick Start

LocoPal currently offers two common paths: create directly in LocoPal Creation, or use the LocoPal Ai API to integrate it into your own business.

Both approaches share the same LocoPal account, model catalog, and billing system. This page focuses on LocoPal Ai and LocoPal Creation.

Step 1: Register or sign in to LocoPal Ai

1. Open LocoPal Ai. If you already have an account, sign in directly; if not, go to the registration page.
2. The current registration page requires a username and password, and SMS verification of a mobile number. The verification method may change with security policy; follow the prompts shown on the registration page.
3. After signing in, confirm the account balance, plan quota, or available credits. Confirm the account is usable before using Creation or the API.

Step 2: Use LocoPal Creation directly

If your goal is to generate content directly, we recommend starting with Creation. It requires no coding and no API key.

1. Open LocoPal Creation.
2. Creation has no separate account. When you are not signed in, the page redirects to the LocoPal sign-in; after you complete authorization it returns to Creation automatically, and you do not need to enter your password again.
3. On the home page, choose Smart Mode, AI Drawing, AI Video, or AI Audio and enter your request; once in the workspace you can also use entries such as Short Drama, Works, Assets, Prompts, Lexicon, and Works Gallery.
4. When you need to keep the person, product, or style consistent, upload a reference image or select an existing asset before submitting.
5. After submitting, view the task status, preview the result, and download it or continue referencing it on the current page. Refreshing the page does not recreate the task; do not resubmit a task that is still running.

Creation's model availability matches the current LocoPal Ai model catalog, and usage is billed uniformly to the current LocoPal account. If a model is unavailable, first check the LocoPal Ai model marketplace to confirm whether that model is in a currently available group.

Step 3: Integrate the API and create an API key

Go to "API Keys" in the LocoPal Ai console and click create. We recommend creating separate keys for "Production Service / Test Environment / Customer App" so you can view logs per application, limit quotas, and promptly disable leaked keys.

When creating a key, confirm the following:

• The key name distinguishes the caller;
• The calling group determines which models this key can see and call;
• Quota and validity period limit abnormal consumption;
• A single key can call the model, image, video, audio, and asset APIs; you do not need different keys for different APIs.

API keys should only be kept in server-side environment variables or a secrets management service. Do not write them into web page source code, mobile app packages, public repositories, logs, or screenshots.

Step 4: Prepare the base address

Default base address:

export LOCOPAL_API_KEY="sk-你的APIKey"
export LOCOPAL_BASE_URL="https://locopalai.com"

The platform console may also show an access address for overseas models or specific network environments, for example:

https://us-api.locopalai.com

Use the address currently shown in the console when integrating. LOCOPAL_BASE_URL should contain only the domain; do not append /v1 again, because the API paths themselves already include /v1 or /api/v1.

Step 5: Query the models available to the current key

curl "$LOCOPAL_BASE_URL/v1/models" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

{
  "object": "list",
  "success": true,
  "data": [
    {
      "id": "doubao-seedance-2.0",
      "object": "model",
      "created": 1626777600,
      "owned_by": "doubaovideo",
      "supported_endpoint_types": ["openai"]
    }
  ]
}

• The model in a request must be the data[].id, not the display name shown on the page;
• A return of "data": [] means the calling group the current key belongs to has no available models; confirm the group configuration first or contact platform support;
• The model catalog changes with account authorization, access address, and platform availability, so we recommend querying it again when the service starts, when a user switches models, or when you receive "model unavailable";
• The same key may see different model sets on locopalai.com and us-api.locopalai.com; whichever address you use, that address's /v1/models is authoritative;
• Whether a model can be called is determined by the current key's /v1/models result; do not hard-code model names.

Use supported_endpoint_types to decide which example to use

data[].supported_endpoint_types tells you directly which type of API this model uses, so you can pick the example accordingly:

A model's supported_endpoint_types may contain several entries at once, meaning it can be called through multiple APIs.

Step 6: Your first text call

curl -X POST "$LOCOPAL_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "从 /v1/models 选择的文本模型 ID",
    "messages": [{ "role": "user", "content": "用三句话介绍这个产品" }],
    "stream": false
  }'

On success, read the text from choices[0].message.content, and save the usage in the response for reconciliation. A reasoning model may spend all of max_tokens on completion_tokens_details.reasoning_tokens; in that case message.content is empty and finish_reason is length. Raise the output limit or switch to a non-reasoning model and try again. With stream: true, read the response chunk by chunk over SSE and finish when you receive [DONE].

Step 7: Your first image call

curl -X POST "$LOCOPAL_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "从 /v1/models 选择的图片模型 ID",
    "prompt": "白色桌面上的一个红苹果，柔和自然光，产品摄影",
    "size": "1024x1024",
    "n": 1
  }'

The response usually returns a url or b64_json in data[]. A returned URL may be temporary, so save the file elsewhere as soon as possible; size, quality, and response_format all depend on the current image model, and some GPT Image models reject response_format and return unknown_parameter, in which case you should remove that field. When an image will serve as a reference for a later video, first ingest it through the asset library API and wait until its status is Active, then reference it with asset://<asset_id>.

Step 8: Your first video call

Video is an async task: the create endpoint returns a task ID, and the query endpoint returns progress and results.

POST /v1/video/generations and POST /v1/videos use the same request body and response format; either one works. The legacy call path is automatically handled by the platform as a video task plugin.

curl -X POST "$LOCOPAL_BASE_URL/v1/video/generations" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "从 /v1/models 选择的视频模型 ID",
  "content": [
    { "type": "text", "text": "清晨的湖边，镜头缓慢向前推进" }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5
}
JSON

{
  "created_at": 1789567067,
  "id": "task-public-id",
  "model": "seedance-2.0-mini",
  "status": "queued",
  "task_id": "task-public-id"
}

The create response should only be relied on for id / task_id, status, model, and created_at; fields such as object and progress may only appear after the first query, so do not treat them as prerequisites for a successful creation.

Save the id from the create response, then query the same task:

export LOCOPAL_TASK_ID="创建响应里的 id"

curl "$LOCOPAL_BASE_URL/v1/video/generations/$LOCOPAL_TASK_ID" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

After the task succeeds, read metadata.url to download or play the result. The platform prefers to return the upstream original video URL; only when the upstream does not return a readable address does it fall back to the platform artifact address. The video parameters returned by the upstream may include:

{
  "metadata": {
    "url": "https://上游原始视频地址",
    "upstream_created": true
  },
  "duration_secs": 5,
  "expires_at": 1790578352,
  "framespersecond": 24,
  "generate_audio": true,
  "ratio": "9:16",
  "resolution": "480p",
  "seed": 20260409,
  "output_format": "mp4",
  "execution_expires_after": 172800
}

Among these fields, duration_secs is the duration; expires_at appears only when the corresponding upstream returns it; the other video parameters likewise appear only when the model and upstream actually return them. Once you have the task ID, even if your local wait times out, you must keep querying the original task and must not create a new one; otherwise you will create duplicate tasks and charges.

If the query result status is failed, read error.code and error.message in the same response. A terminal video task failure usually uses video_generation_failed; error.message is a readable reason after platform cleanup, so do not try to parse the JSON inside it:

{
  "id": "task-public-id",
  "status": "failed",
  "error": {
    "code": "video_generation_failed",
    "message": "音频素材缓冲失败: 音频地址必须是 http(s)"
  }
}

Step 9: Your first text-to-speech call

The platform provides an OpenAI-compatible POST /v1/audio/speech endpoint. Availability depends on the current API key's group and model catalog; the supported voices, formats, and speed parameters depend on the actual model.

curl -X POST "$LOCOPAL_BASE_URL/v1/audio/speech" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "从 /v1/models 选择的音频模型 ID",
    "input": "欢迎使用 LocoPal Ai。",
    "voice": "alloy",
    "response_format": "mp3"
  }' \
  --output speech.mp3

On success, the response body is binary audio, not JSON; the example saves it to speech.mp3 with --output. The async status and artifacts of other audio tasks can be queried in "Task Logs".

Step 10: Your first asset call

curl -X POST "$LOCOPAL_BASE_URL/api/v1/materials/groups" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "name": "我的角色素材",
  "description": "视频参考图",
  "type": "virtual"
}
JSON

{
  "code": 0,
  "data": {
    "group": {
      "id": "group-1789069780-5762d1",
      "platform_group_id": "group-1789069780-5762d1",
      "name": "我的角色素材",
      "type": "virtual",
      "description": "视频参考图",
      "created_at": 1789069780,
      "updated_at": 1789069780
    }
  },
  "msg": "素材分组已创建"
}

Save data.group.id, then submit the image and poll the status:

curl -X POST "$LOCOPAL_BASE_URL/api/v1/materials/assets" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"group_id":"group-id","title":"角色正面图","image_url":"https://你的对象存储域名/person.png"}'

curl "$LOCOPAL_BASE_URL/api/v1/materials/assets/asset-id" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

image_url must be an http(s) address that can be downloaded directly from the public internet; you can also submit a data_url within the API's limits. Once data.asset.status becomes Active, you can reference it in video requests with asset://<asset_id>. See Asset Library API Overview for the full parameters and error descriptions.

Step 11: Portrait assets (optional)

Portrait assets must be captured and authorized by the person themselves by scanning a QR code with a phone; an ordinary image upload cannot replace this. The console flow is "Asset Library Management → New Group → Portrait Assets → Generate QR Code → The person scans it → Scan complete, start sync"; for the API flow, see Create a Portrait QR Code Session.

Next steps