# FAQ



Difference between requesting an API key via email vs membership [#difference-between-requesting-an-api-key-via-email-vs-membership]

There is no functional difference. Membership lets you get a key instantly (good for quick start). Email requests require manual approval (up to 5 business days), but we will also use that email address to send important maintenance notifications.

Receiving maintenance or downtime notifications [#receiving-maintenance-or-downtime-notifications]

Before each maintenance/downtime, we will notify users via PixAI's announcements and official social channels (e.g., X/Twitter). In addition, we will proactively email maintenance/downtime notices to the email address you used to contact us, to minimize impact on your business.

If you want notifications sent to a different email address, or you want to stop receiving email notifications, please tell us in your email.

API-generated images and public history [#api-generated-images-and-public-history]

Generations triggered via API are private and will not appear in your account's public generation history.

Supported languages for support [#supported-languages-for-support]

We currently provide English and Japanese email support for technical questions and business coordination.


# PixAI API Documentation





The PixAI API lets your application generate anime-style AI artwork with the same models that power [pixai.art](https://pixai.art), such as Tsubaki.2, Haruka v2 and Hoshino v2. It is a REST API served from `https://api.pixai.art`: you authenticate with an API key, submit a generation task, and collect the finished images when the task completes.

How the API works [#how-the-api-works]

1. **Get an API key.** Request access from the PixAI API team or create a key from your PixAI profile, then send it as `Authorization: Bearer <key>` on every call. See [How can I use PixAI API?](/en/docs/quick-start/enroll-in-api).
2. **Create a task.** `POST /v2/image/create` with a prompt, a model and optional settings such as aspect ratio or style. The response is a task in `waiting` status.
3. **Wait for the result.** Poll `GET /v1/task/{taskId}` no more than once every 1.5 seconds, or register a [webhook](/en/docs/references/webhook) and receive the task object when it finishes.
4. **Download the images.** The completed task lists media URLs; `GET /v1/media/{mediaId}` returns the media object and `GET /v1/media/{mediaId}/image` redirects to the file. Store the files you need: generated media is not kept indefinitely.

Browse the documentation [#browse-the-documentation]

<Cards>
  <Card title="Quick Start" description="Get API access, make your first request and learn the current limits." href="/en/docs/quick-start/enroll-in-api" />

  <Card title="Create an image (API v2)" description="Reference for POST /v2/image/create with aspect ratios, modes and style presets." href="/en/docs/api-v2/image/createImage" />

  <Card title="Tasks and media (API v1)" description="Read task status and retrieve or upload media by ID." href="/en/docs/api/task/getTask" />

  <Card title="Models" description="Available image models with IDs, versions and allowed sampling methods." href="/en/docs/references/models" />

  <Card title="Supported resolutions" description="Output sizes for each aspect ratio and resolution tier." href="/en/docs/references/supported-resolutions" />

  <Card title="Webhooks" description="Receive task status updates by POST instead of polling." href="/en/docs/references/webhook" />

  <Card title="Limits" description="Concurrency limits, polling guidance and features not yet available in the API." href="/en/docs/quick-start/limits" />

  <Card title="FAQ" description="Keys by email versus membership, maintenance notices, privacy of API generations." href="/en/docs/faq" />

  <Card title="Copyright and licensing" description="Who owns generated images and how PixAI models may be used commercially." href="/en/docs/about/copyright" />
</Cards>

Machine-readable versions [#machine-readable-versions]

* [/llms.txt](/llms.txt) lists every page of this documentation with a one-line summary; [/llms-full.txt](/llms-full.txt) contains all pages in one Markdown file.
* Append `.mdx` to any page URL to fetch that page as Markdown, for example [/en/docs/quick-start/limits.mdx](/en/docs/quick-start/limits.mdx).

Need help? [#need-help]

Write to [api@withpixai.art](mailto:api@withpixai.art&#x29; or join the **#api-beta-test** channel on the [PixAI Discord](https://discord.com/invite/pixai). See [User feedback](/en/docs/about/feedback) for details.


# Copyright & related rights



For details, please refer to:

* License: [Apache 2.0](http://www.apache.org/licenses/LICENSE-2.0.html)
* Terms of Service: [pixai.art/terms](https://pixai.art/terms)

Users own the copyrights to images generated through the API. PixAI does not claim any copyright over user-generated works. However, users must ensure that generated content does not infringe any third-party rights and complies with applicable local laws and regulations.

PixAI's official models (e.g. Haruka, Tsubaki) are copyrighted by PixAI. We grant approved users the right to use these models for commercial activities, but reselling or redistributing the model files themselves is prohibited.


# User feedback





If you have any questions or feedback during the beta test, feel free to contact us at [api@withpixai.art](mailto:api@withpixai.art&#x29;, or join our official Discord and submit your feedback in **#api-beta-test**.

[<img alt="discord channel" src="__img0" />](https://discord.com/invite/pixai)


# Models



Recommended Models [#recommended-models]

| Model      | Model ID            | Advantage                                                                                                                                                    |
| ---------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Tsubaki.2  | 1983308862240288769 | Strong Prompt Understanding & Execution. Seamless Anatomy & Precision. Wider Stylistic Adaptability Across Aesthetics. Enhanced Multi-Character Interaction. |
| Haruka v2  | 1861558740588989558 | Stable quality, refined details, and accurate hands                                                                                                          |
| Hoshino v2 | 1954632828118619567 | A highly popular style in Japan                                                                                                                              |

Model List [#model-list]

Haruka v2 [#haruka-v2]

* Model Type: `SDXL`
* Model Version ID: `1861558740588989558` (use this as modelId in API)
* Link: [https://pixai.art/model/1861558737426484240-Haruka-v2](https://pixai.art/model/1861558737426484240-Haruka-v2)

**Allowed Sampling Methods**

| Key             | Value                                                                                                                                           |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| samplingMethods | Euler a, Euler, LMS, Heun, DPM2 Karras, DPM2 a Karras, DDIM, DPM++ 2M Karras, DPM++ 2S a Karras, DPM++ SDE Karras, DPM++ 2M SDE Karras, Restart |

Tsubaki.2 [#tsubaki2]

* Model Type: `DIT`
* Model Version ID: `1983308862240288769` (use this as modelId in API)
* Link: [https://pixai.art/model/1982880136609467518-Tsubaki.2](https://pixai.art/model/1982880136609467518-Tsubaki.2)

**Allowed Sampling Methods**

| Key             | Value                                                                                                                                           |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| samplingMethods | Euler a, Euler, LMS, Heun, DPM2 Karras, DPM2 a Karras, DDIM, DPM++ 2M Karras, DPM++ 2S a Karras, DPM++ SDE Karras, DPM++ 2M SDE Karras, Restart |

Hoshino v2 [#hoshino-v2]

* Model Type: `SDXL`
* Model Version ID: `1954632828118619567` (use this as modelId in API)
* Link: [https://pixai.art/model/1954632827019711809-Hoshino-v2](https://pixai.art/model/1954632827019711809-Hoshino-v2)

**Allowed Sampling Methods**

| Key             | Value                                                                                                                                           |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| samplingMethods | Euler a, Euler, LMS, Heun, DPM2 Karras, DPM2 a Karras, DDIM, DPM++ 2M Karras, DPM++ 2S a Karras, DPM++ SDE Karras, DPM++ 2M SDE Karras, Restart |


# Supported Resolutions



The v2 API uses `aspectRatio` + `size` to determine the output resolution. All dimensions are divisible by 16 as required by diffusion backends.

| Aspect Ratio | 1k (Width × Height) | 1.5k (Width × Height) |
| ------------ | ------------------- | --------------------- |
| 1:1          | 1024 × 1024         | 1536 × 1536           |
| 2:3          | 848 × 1280          | 1024 × 1536           |
| 3:2          | 1280 × 848          | 1536 × 1024           |
| 3:4          | 864 × 1152          | 1152 × 1536           |
| 4:3          | 1152 × 864          | 1536 × 1152           |
| 3:5          | 768 × 1280          | 912 × 1536            |
| 5:3          | 1280 × 768          | 1536 × 912            |
| 9:16         | 720 × 1280          | 864 × 1536            |
| 16:9         | 1280 × 720          | 1536 × 864            |
| 1:3          | 512 × 1536          | 512 × 1536            |
| 3:1          | 1536 × 512          | 1536 × 512            |

* Default: `aspectRatio: "1:1"`, `size: "1k"` → 1024 × 1024.
* `1.5k` caps the longest edge at 1536 px. For extreme ratios (1:3, 3:1) the dimensions are identical to 1k.
* All aspect ratios are available across all model types (SDXL, DiT, Tsubaki.2).


# Webhook



Developers can configure one or more webhooks to receive notifications about the status of tasks.

When a task is started, completed, canceled or failed, the platform will send a POST request to the specified URL.

You can configure it on [your profile page](https://pixai.art/profile/edit/api).

If you are using `callbackUrl` in the `REST` API, the body format follows this format:

```json
{
    "action": "task_running",
    "data": {
        "id": "1829312678046282149",
        "status": "running",
        "createdAt": "2024-12-27T09:25:46.436Z",
        "updatedAt": "2024-12-27T09:26:01.912Z",
        "outputs": {
            "mediaIds": [],
            "mediaUrls": []
        }
    }
}
```


# How can I use PixAI API?



Method A (Recommended) [#method-a-recommended]

Please contact PixAI API Team at [api@withpixai.art](mailto:api@withpixai.art) and provide the following information in your email:

* Company Name: (Your company/organization name)
* Your Position: (Your role in the company)
* Estimated Usage: (Expected API usage volume, e.g., number of requests per month)
* Purpose: (Brief description of how you plan to use the API)

Once your request is reviewed, our team will follow up with you within 5 business days to discuss the next steps.

Method B [#method-b]

Apply for the beta test via PixAI website or [this form](https://docs.google.com/forms/d/1hJJYLOWhiq3HAH06kNEyiG1ISLDhiIh-8CqfndikN40/viewform?edit_requested=true).

Once approved, you will receive an email with your API access result and guidance on the next steps.

If you have any questions, feedback, or suggestions, please feel free to reach out to us at [api@withpixai.art](mailto:api@withpixai.art).


# Your First API Call





Base URL: `https://api.pixai.art/v2`

Authentication: add `Authorization: Bearer YOUR_API_KEY` header to every request. See [How can I use PixAI API?](/en/docs/quick-start/enroll-in-api) to get an API key.

Steps [#steps]

<div className="fd-steps">
  <div className="fd-step">
    Submit a Task [#submit-a-task-step]

    Send a `POST /image/create`. The required fields are `modelVersionId` and `prompt`.

    ```bash
    curl -X POST https://api.pixai.art/v2/image/create \
      -H "Authorization: Bearer $PIXAI_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "modelVersionId": "1983308862240288769",
        "prompt": "1girl, green hair, masterpiece, best quality, solo, standing, flower",
        "aspectRatio": "9:16",
        "mode": "standard"
      }'
    ```

    Response:

    ```json
    {
      "id": "TASK_ID",
      "status": "waiting",
      "createdAt": "2026-03-04T04:32:10.635Z",
      "updatedAt": "2026-03-04T04:32:10.635Z",
      "outputs": {
        "mediaIds": [],
        "mediaUrls": []
      }
    }
    ```

    Note the `id` in the response — this is your `TASK_ID`, used in the next step.

    <Callout type="info">
      Find a `modelVersionId` from the model version URL on PixAI: `https://pixai.art/model/<id>/<modelVersionId>` — the last segment is the `modelVersionId`. See [Models](/en/docs/references/models#recommended-models) for recommended options.
    </Callout>
  </div>

  <div className="fd-step">
    Poll for Status [#poll-for-status-step]

    Repeat until `status` reaches a terminal state.

    ```bash
    curl https://api.pixai.art/v1/task/TASK_ID \
      -H "Authorization: Bearer $PIXAI_API_KEY"
    ```

    | Status      | Meaning                     |
    | :---------- | :-------------------------- |
    | `waiting`   | Task is queued              |
    | `running`   | Generation in progress      |
    | `completed` | Finished, outputs are ready |
    | `failed`    | Generation failed           |
    | `cancelled` | Task was cancelled          |

    When `completed`, `outputs.mediaUrls` contains the image URLs.

    <Callout type="warn">
      Poll no more frequently than once every **1.5 seconds**. Use exponential backoff on retries. Each account allows up to 10 concurrent tasks in `waiting` or `running` state. See [Limits](/en/docs/quick-start/limits) for details.
    </Callout>
  </div>

  <div className="fd-step">
    Download the Image [#download-the-image-step]

    ```bash
    curl -L "MEDIA_URL" -o output.png
    # or via media ID:
    curl -L https://api.pixai.art/v1/media/MEDIA_ID/image \
      -H "Authorization: Bearer $PIXAI_API_KEY" -o output.png
    ```

    <Callout type="warn">
      Generated images are **not permanently retained** — download them as soon as the task completes.
    </Callout>
  </div>
</div>

Next Steps [#next-steps]

* [Models](/en/docs/references/models) — browse available models
* [Webhook](/en/docs/references/webhook) — receive task updates without polling


# About this doc



This documentation is designed to help you get started with the PixAI platform. You can use the PixAI API to build applications that leverage the power of AI to enhance your images.



<Cards>
  <Card title="RESTful API" href="/en/docs/api-v2/image/createImage" />

  <Card title="My API Keys" href="https://pixai.art/profile/edit/api" />
</Cards>


# Limits



Rate limits [#rate-limits]

* Each API account has a concurrency limit of 10 tasks. That means up to 10 tasks can be in `pending` or `running` status at the same time.
* We don't currently enforce a request rate limit on API calls. Please use the API responsibly—for example, use exponential backoff for retries and avoid polling more frequently than once every 1.5 seconds.

Feature limitations [#feature-limitations]

* Video generation is not supported.
* PixAI Reference Pro, PixAI Edit, and PixAI Edit Lite are not supported yet (these features are under active development).


# Get media by ID



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/openapi-spec.yaml&#x22;" operations="[{&#x22;path&#x22;:&#x22;/media/{mediaId}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Get media image by ID



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/openapi-spec.yaml&#x22;" operations="[{&#x22;path&#x22;:&#x22;/media/{mediaId}/image&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Upload an image or video



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/openapi-spec.yaml&#x22;" operations="[{&#x22;path&#x22;:&#x22;/media/upload&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Create a generation task



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/openapi-spec.yaml&#x22;" operations="[{&#x22;path&#x22;:&#x22;/task&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# Get task detail by ID



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/openapi-spec.yaml&#x22;" operations="[{&#x22;path&#x22;:&#x22;/task/{taskId}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# Create an image generation task



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/openapi-spec.v2.yaml&#x22;" operations="[{&#x22;path&#x22;:&#x22;/image/create&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# よくあるご質問（FAQ）



Q：メール申請とメンバーシップ加入で取得するAPIキーに違いはありますか？ [#qメール申請とメンバーシップ加入で取得するapiキーに違いはありますか]

A： 機能面での違いは一切ございません。 メンバーシップにご加入いただくと即時にキーが発行されるため、お急ぎの場合に最適です。一方、メールでの申請はスタッフによる審査（最大5営業日）が必要ですが、申請いただいたメールアドレス宛に、システムメンテナンス等の重要なお知らせを直接お送りできるというメリットがあります。

Q：システムメンテナンスや計画停止の通知はどのように受け取れますか？ [#qシステムメンテナンスや計画停止の通知はどのように受け取れますか]

A： メンテナンス等の予定については、事前に PixAI公式サイト内のお知らせおよび公式 X（旧 Twitter）等で全ユーザーにお知らせいたします。 これに加え、API利用者様に対しては、ご登録いただいたメールアドレス宛に個別で通知をお送りし、お客様の業務への影響を最小限に抑えるよう努めております。

※通知先の変更や配信停止をご希望の場合は、お手数ですがメールにてその旨をご連絡ください。

Q：APIを通じて生成した画像は、PixAIサイト上の生成履歴に残りますか？ [#qapiを通じて生成した画像はpixaiサイト上の生成履歴に残りますか]

A： いいえ、残りません。 APIを利用した生成履歴はユーザー様のプライベートなものとして扱われ、お客様のプロフィールページに表示されることはありません。

Q：メールでの申込みや問い合わせは何語で送ればよいですか？問い合わせの対応言語を教えてください。 [#qメールでの申込みや問い合わせは何語で送ればよいですか問い合わせの対応言語を教えてください]

A： 現在、日本語と英語でサポートを提供しております。 ビジネスや技術的なご質問など、どちらかご都合の良い言語でお気軽にお問い合わせください。


# PixAI API ドキュメント





PixAI API を使うと、[pixai.art](https://pixai.art) と同じモデル（Tsubaki.2、Haruka v2、Hoshino v2 など）でアニメ風の AI イラストをアプリケーションから生成できます。`https://api.pixai.art` で提供される REST API で、API キーで認証し、生成タスクを送信し、完了後に画像を取得する流れです。

API の流れ [#api-の流れ]

1. **API キーを取得する。** PixAI API チームに申請するか、PixAI のプロフィールでキーを作成し、すべてのリクエストに `Authorization: Bearer <key>` を付けます。詳しくは [PixAI API を利用するには](/ja/docs/quick-start/enroll-in-api)。
2. **タスクを作成する。** プロンプト、モデル、アスペクト比やスタイルなどの任意設定を `POST /v2/image/create` に送ると、`waiting` 状態のタスクが返ります。
3. **完了を待つ。** `GET /v1/task/{taskId}` を 1.5 秒に 1 回以内の頻度でポーリングするか、[Webhook](/ja/docs/references/webhook) を登録して完了時にタスクを受け取ります。
4. **画像をダウンロードする。** 完了したタスクにはメディア URL が含まれます。`GET /v1/media/{mediaId}` はメディア情報を、`GET /v1/media/{mediaId}/image` はファイルへのリダイレクトを返します。生成物は無期限には保存されないため、必要なファイルは保存してください。

ドキュメントを探す [#ドキュメントを探す]

<Cards>
  <Card title="クイックスタート" description="API アクセスの取得、最初のリクエスト、現在の制限。" href="/ja/docs/quick-start/enroll-in-api" />

  <Card title="画像生成（API v2）" description="アスペクト比・モード・スタイルプリセットを含む POST /v2/image/create のリファレンス。" href="/ja/docs/api-v2/image/createImage" />

  <Card title="タスクとメディア（API v1）" description="タスク状態の取得、メディアの取得とアップロード。" href="/ja/docs/api/task/getTask" />

  <Card title="モデル" description="利用可能な画像モデルの ID・バージョン・サンプリング方法。" href="/ja/docs/references/models" />

  <Card title="対応解像度" description="アスペクト比と解像度ティアごとの出力サイズ。" href="/ja/docs/references/supported-resolutions" />

  <Card title="Webhook" description="ポーリングの代わりに POST でタスクの状態更新を受け取る。" href="/ja/docs/references/webhook" />

  <Card title="制限" description="同時実行数、ポーリングの目安、API で未対応の機能。" href="/ja/docs/quick-start/limits" />

  <Card title="よくあるご質問" description="メールとメンバーシップによるキー取得の違い、メンテナンス通知、API 生成物の公開範囲。" href="/ja/docs/faq" />

  <Card title="著作権とライセンス" description="生成画像の権利と PixAI モデルの商用利用条件。" href="/ja/docs/about/copyright" />
</Cards>

機械可読版 [#機械可読版]

* [/llms.txt](/llms.txt) は本ドキュメントの全ページを一行要約付きで一覧し、[/llms-full.txt](/llms-full.txt) は全ページを 1 つの Markdown にまとめたものです。
* 任意のページ URL の末尾に `.mdx` を付けると Markdown として取得できます。例: [/ja/docs/quick-start/limits.mdx](/ja/docs/quick-start/limits.mdx)

サポート [#サポート]

[api@withpixai.art](mailto:api@withpixai.art) までメールいただくか、[PixAI 公式 Discord](https://discord.com/invite/pixai&#x29; の **#api-beta-test** チャンネルへどうぞ。詳細は [フィードバック](/ja/docs/about/feedback) をご覧ください。


# 著作権および関連する権利



詳細は以下をご参照ください。

* ライセンス: [Apache 2.0](http://www.apache.org/licenses/LICENSE-2.0.html)
* 利用規約: [pixai.art/terms](https://pixai.art/terms)

APIを通じて生成された画像の著作権は、すべてユーザーに帰属します。PixAIがユーザーの生成作品に対して著作権を主張することはありません。ただし、生成されたコンテンツが第三者の権利を侵害していないこと、およびお住まいの国や地域で適用される法令を遵守していることについては、ユーザー自身の責任でご確認いただく必要があります。

PixAI の公式モデル（例：Haruka、Tsubaki）の著作権は PixAI に帰属します。API利用の承認を得たユーザーには商用利用の権利を付与しますが、モデルファイル自体の転売・再配布は禁止されています。


# お問い合わせ





βテスト中にご不明点やフィードバックがございましたら、[api@withpixai.art](mailto:api@withpixai.art&#x29;までお問い合わせいただくか、公式Discordに参加して **#api-beta-test** チャンネルにてフィードバックをご投稿ください。

[<img alt="discord channel" src="__img0" />](https://discord.com/invite/pixai)


# モデル



推奨モデル [#推奨モデル]

| モデル        | モデル ID              | 特長                                                                    |
| ---------- | ------------------- | --------------------------------------------------------------------- |
| Tsubaki.2  | 1983308862240288769 | プロンプト理解と実行力の強化、自然な骨格構造と精密なディテール、多様なテイストへの幅広い適応力、複数キャラクターのインタラクションの進化。 |
| Haruka v2  | 1861558740588989558 | 品質が安定しており、緻密な細部表現と、崩れにくい正確な手の描写を兼ね備えた万能モデル。                           |
| Hoshino v2 | 1954632828118619567 | 日本で人気の高い作風。                                                           |

モデル一覧 [#モデル一覧]

Haruka v2 [#haruka-v2]

* モデルタイプ: `SDXL`
* モデルバージョン ID: `1861558740588989558` （API の modelId として使用）
* リンク: [https://pixai.art/model/1861558737426484240-Haruka-v2](https://pixai.art/model/1861558737426484240-Haruka-v2)

**許可されているサンプリング方法**

| Key             | Value                                                                                                                                           |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| samplingMethods | Euler a, Euler, LMS, Heun, DPM2 Karras, DPM2 a Karras, DDIM, DPM++ 2M Karras, DPM++ 2S a Karras, DPM++ SDE Karras, DPM++ 2M SDE Karras, Restart |

Tsubaki.2 [#tsubaki2]

* モデルタイプ: `DIT`
* モデルバージョン ID: `1983308862240288769` （API の modelId として使用）
* リンク: [https://pixai.art/model/1982880136609467518-Tsubaki.2](https://pixai.art/model/1982880136609467518-Tsubaki.2)

**許可されているサンプリング方法**

| Key             | Value                                                                                                                                           |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| samplingMethods | Euler a, Euler, LMS, Heun, DPM2 Karras, DPM2 a Karras, DDIM, DPM++ 2M Karras, DPM++ 2S a Karras, DPM++ SDE Karras, DPM++ 2M SDE Karras, Restart |

Hoshino v2 [#hoshino-v2]

* モデルタイプ: `SDXL`
* モデルバージョン ID: `1954632828118619567` （API の modelId として使用）
* リンク: [https://pixai.art/model/1954632827019711809-Hoshino-v2](https://pixai.art/model/1954632827019711809-Hoshino-v2)

**許可されているサンプリング方法**

| Key             | Value                                                                                                                                           |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| samplingMethods | Euler a, Euler, LMS, Heun, DPM2 Karras, DPM2 a Karras, DDIM, DPM++ 2M Karras, DPM++ 2S a Karras, DPM++ SDE Karras, DPM++ 2M SDE Karras, Restart |


# 対応解像度



v2 API は `aspectRatio` + `size` の組み合わせで出力解像度を決定します。すべての寸法はディフュージョンバックエンドの要件に従い 16 の倍数です。

| アスペクト比 | 1k（幅 × 高さ）  | 1.5k（幅 × 高さ） |
| ------ | ----------- | ------------ |
| 1:1    | 1024 × 1024 | 1536 × 1536  |
| 2:3    | 848 × 1280  | 1024 × 1536  |
| 3:2    | 1280 × 848  | 1536 × 1024  |
| 3:4    | 864 × 1152  | 1152 × 1536  |
| 4:3    | 1152 × 864  | 1536 × 1152  |
| 3:5    | 768 × 1280  | 912 × 1536   |
| 5:3    | 1280 × 768  | 1536 × 912   |
| 9:16   | 720 × 1280  | 864 × 1536   |
| 16:9   | 1280 × 720  | 1536 × 864   |
| 1:3    | 512 × 1536  | 512 × 1536   |
| 3:1    | 1536 × 512  | 1536 × 512   |

* デフォルト: `aspectRatio: "1:1"`、`size: "1k"` → 1024 × 1024。
* `1.5k` の最長辺は 1536 px です。極端な比率（1:3、3:1）では 1k と同じ寸法になります。
* すべてのアスペクト比はすべてのモデルタイプ（SDXL、DiT、Tsubaki.2）で利用可能です。


# Webhook



開発者はウェブフックを設定することで、タスクのステータスに関する通知を受け取ることができます。

タスクが開始、完了、キャンセル、または失敗した際に、指定した URL に POST リクエストが送信されます。

[プロフィールページ](https://pixai.art/profile/edit/api)で設定できます。

REST API で `callbackUrl` を使用する場合、ボディは以下の形式になります:

```json
{
    "action": "task_running",
    "data": {
        "id": "1829312678046282149",
        "status": "running",
        "createdAt": "2024-12-27T09:25:46.436Z",
        "updatedAt": "2024-12-27T09:26:01.912Z",
        "outputs": {
            "mediaIds": [],
            "mediaUrls": []
        }
    }
}
```


# PixAI APIを使用するには？



API の利用をご希望の方は、以下のいずれかの方法でお申し込みください。

方法 A（推奨）：メールでのお申込み [#方法-a推奨メールでのお申込み]

PixAI API サポートチーム（[api@withpixai.art](mailto:api@withpixai.art)）まで、以下の情報を添えてご連絡ください。

* 会社名: (貴社/団体名)
* 役職: (社内でのご担当の役割)
* 推定利用量: (API の予想利用量。例：月間リクエスト数)
* 利用目的: (API の利用計画の簡単な説明)

お申し込み内容を確認後、5営業日以内に担当者より次のステップについてご案内いたします。

方法 B：ベータテストへの申請 [#方法-bベータテストへの申請]

ご自身の PixAI プロフィールページ、または[こちらのフォーム](https://docs.google.com/forms/d/1-TisijzbR7lpsSfhJZzVpCkHunGEOOoJuRE6iIKlHpc/viewform?edit_requested=true)からベータテストにお申し込みください。

承認後、API アクセス権限の付与と今後の手順に関するご案内メールをお送りします。

ご不明な点やフィードバック、ご提案がございましたら、お気軽に [api@withpixai.art](mailto:api@withpixai.art) までお問い合わせください。


# 最初のAPIリクエスト





ベースURL: `https://api.pixai.art/v2`

認証: すべてのリクエストに `Authorization: Bearer YOUR_API_KEY` ヘッダーを追加してください。APIキーの取得方法は[PixAI APIを使用するには？](/ja/docs/quick-start/enroll-in-api)をご参照ください。

手順 [#手順]

<div className="fd-steps">
  <div className="fd-step">
    タスクを送信する [#タスクを送信する-step]

    `POST /image/create` を送信します。必須フィールドは `modelVersionId` と `prompt` です。

    ```bash
    curl -X POST https://api.pixai.art/v2/image/create \
      -H "Authorization: Bearer $PIXAI_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "modelVersionId": "1983308862240288769",
        "prompt": "1girl, green hair, masterpiece, best quality, solo, standing, flower",
        "aspectRatio": "9:16",
        "mode": "standard"
      }'
    ```

    レスポンス:

    ```json
    {
      "id": "TASK_ID",
      "status": "waiting",
      "createdAt": "2026-03-04T04:32:10.635Z",
      "updatedAt": "2026-03-04T04:32:10.635Z",
      "outputs": {
        "mediaIds": [],
        "mediaUrls": []
      }
    }
    ```

    レスポンス内の `id` を控えておいてください。これが次のステップで使用する `TASK_ID` です。

    <Callout type="info">
      `modelVersionId` は PixAI のモデルバージョン URL（`https://pixai.art/model/<id>/<modelVersionId>`）の最後のセグメントです。推奨モデルは[モデル一覧](/ja/docs/references/models#recommended-models)をご参照ください。
    </Callout>
  </div>

  <div className="fd-step">
    ステータスを確認する [#ステータスを確認する-step]

    `status` が終了状態になるまで繰り返します。

    ```bash
    curl https://api.pixai.art/v1/task/TASK_ID \
      -H "Authorization: Bearer $PIXAI_API_KEY"
    ```

    | ステータス       | 意味           |
    | :---------- | :----------- |
    | `waiting`   | タスクはキュー待ち中   |
    | `running`   | 生成処理中        |
    | `completed` | 完了、出力が利用可能   |
    | `failed`    | 生成に失敗        |
    | `cancelled` | タスクがキャンセルされた |

    `completed` の場合、`outputs.mediaUrls` に画像 URL が含まれます。

    <Callout type="warn">
      ポーリングは **1.5秒** に1回以下にしてください。再試行時はエクスポネンシャル・バックオフを使用してください。各アカウントでは `waiting` または `running` 状態のタスクを最大10件まで同時に実行できます。詳細は[制限事項](/ja/docs/quick-start/limits)をご参照ください。
    </Callout>
  </div>

  <div className="fd-step">
    画像をダウンロードする [#画像をダウンロードする-step]

    ```bash
    curl -L "MEDIA_URL" -o output.png
    # またはメディアIDで:
    curl -L https://api.pixai.art/v1/media/MEDIA_ID/image \
      -H "Authorization: Bearer $PIXAI_API_KEY" -o output.png
    ```

    <Callout type="warn">
      生成された画像は **永続的に保存されません**。タスクが完了したらすぐにダウンロードしてください。
    </Callout>
  </div>
</div>

次のステップ [#次のステップ]

* [モデル](/ja/docs/references/models) — 利用可能なモデルを確認
* [Webhook](/ja/docs/references/webhook) — ポーリングなしでタスクの更新を受け取る


# このドキュメントについて



このドキュメントは、PixAI プラットフォームを使い始めるためのガイドです。PixAI API を使用して、AI の力を活用した画像生成アプリケーションを構築できます。



<Cards>
  <Card title="RESTful API" href="/ja/docs/api-v2/image/createImage" />

  <Card title="APIキー管理" href="https://pixai.art/profile/edit/api" />
</Cards>


# 制限事項



レート制限 [#レート制限]

* 最大同時実行数に関しては、1アカウントにつき最大10タスクまでとなります（つまり、`pending` または `running` の状態にあるタスクの合計数です）。
* 現時点では厳格な制限は設けておりませんが、良識ある範囲でのご利用をお願いいたします。再試行時のエクスポネンシャル・バックオフの実装や、1.5秒間隔未満の過度なポーリングはお控えください。

機能制限 [#機能制限]

* 動画生成機能は現在サポート対象外です。
* PixAI Reference Pro、PixAI Edit、PixAI Edit Lite はまだ未対応です（これらの機能は現在積極的に開発中です）。


# メディアの取得



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/openapi-spec.ja.yaml&#x22;" operations="[{&#x22;path&#x22;:&#x22;/media/{mediaId}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# IDでメディア画像へのリダイレクト



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/openapi-spec.ja.yaml&#x22;" operations="[{&#x22;path&#x22;:&#x22;/media/{mediaId}/image&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# 画像・動画のアップロード



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/openapi-spec.ja.yaml&#x22;" operations="[{&#x22;path&#x22;:&#x22;/media/upload&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# 生成タスクの作成



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/openapi-spec.ja.yaml&#x22;" operations="[{&#x22;path&#x22;:&#x22;/task&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# タスク詳細の取得



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/openapi-spec.ja.yaml&#x22;" operations="[{&#x22;path&#x22;:&#x22;/task/{taskId}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# 画像生成タスクの作成



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/openapi-spec.v2.ja.yaml&#x22;" operations="[{&#x22;path&#x22;:&#x22;/image/create&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# 자주 묻는 질문



이메일로 API 키를 신청하는 것과 멤버십 신청의 차이는 무엇인가요? [#이메일로-api-키를-신청하는-것과-멤버십-신청의-차이는-무엇인가요]

기능적인 차이는 없습니다. 멤버십으로 신청하면 키를 즉시 발급받을 수 있어 빠르게 시작할 수 있습니다.
이메일 신청은 수동 검토가 필요하며(영업일 기준 최대 5일), 대신 해당 이메일로 중요한 유지보수 안내도 함께 발송해 드립니다.

유지보수 또는 장애 알림은 어떻게 받을 수 있나요? [#유지보수-또는-장애-알림은-어떻게-받을-수-있나요]

유지보수 또는 장애 발생 전에 PixAI 공지사항 및 공식 소셜 채널(X/Twitter 등)을 통해 안내합니다. 또한 문의 시 사용하신 이메일로도 유지보수/장애 안내 메일을 발송하여 업무 영향이 최소화되도록 하고 있습니다.

알림 수신 이메일 변경 또는 메일 알림 중단을 원하시면 이메일로 알려주세요.

API로 생성한 이미지와 공개 히스토리 [#api로-생성한-이미지와-공개-히스토리]

API를 통해 생성된 이미지는 비공개로 처리되며, 계정의 공개 생성 기록에는 표시되지 않습니다.

기술 지원 제공 언어 [#기술-지원-제공-언어]

현재 기술 지원 및 비즈니스 커뮤니케이션은 이메일로 영어와 일본어를 지원합니다.


# PixAI API 문서





PixAI API를 사용하면 [pixai.art](https://pixai.art)와 동일한 모델(Tsubaki.2, Haruka v2, Hoshino v2 등)로 애니메이션 스타일의 AI 아트를 애플리케이션에서 생성할 수 있습니다. `https://api.pixai.art`에서 제공되는 REST API로, API 키로 인증하고 생성 작업을 제출한 뒤 작업이 완료되면 이미지를 가져오는 방식입니다.

API 동작 방식 [#api-동작-방식]

1. **API 키 받기.** PixAI API 팀에 신청하거나 PixAI 프로필에서 키를 만든 뒤, 모든 요청에 `Authorization: Bearer <key>` 헤더를 보냅니다. 자세한 내용은 [PixAI API 사용 방법](/ko/docs/quick-start/enroll-in-api)을 참고하세요.
2. **작업 만들기.** 프롬프트, 모델, 화면 비율이나 스타일 같은 선택 설정을 `POST /v2/image/create`로 보내면 `waiting` 상태의 작업이 반환됩니다.
3. **완료 기다리기.** `GET /v1/task/{taskId}`를 1.5초에 한 번 이하로 폴링하거나, [Webhook](/ko/docs/references/webhook)을 등록해 완료 시 작업 객체를 받습니다.
4. **이미지 다운로드.** 완료된 작업에는 미디어 URL이 포함됩니다. `GET /v1/media/{mediaId}`는 미디어 정보를, `GET /v1/media/{mediaId}/image`는 파일로 리디렉션을 반환합니다. 생성물은 무기한 보관되지 않으므로 필요한 파일은 저장해 두세요.

문서 둘러보기 [#문서-둘러보기]

<Cards>
  <Card title="빠른 시작" description="API 액세스 받기, 첫 요청 보내기, 현재 제한 사항." href="/ko/docs/quick-start/enroll-in-api" />

  <Card title="이미지 생성 (API v2)" description="화면 비율, 모드, 스타일 프리셋을 포함한 POST /v2/image/create 참조." href="/ko/docs/api-v2/image/createImage" />

  <Card title="작업과 미디어 (API v1)" description="작업 상태 조회, 미디어 조회 및 업로드." href="/ko/docs/api/task/getTask" />

  <Card title="모델" description="사용 가능한 이미지 모델의 ID, 버전, 샘플링 방법." href="/ko/docs/references/models" />

  <Card title="지원 해상도" description="화면 비율과 해상도 등급별 출력 크기." href="/ko/docs/references/supported-resolutions" />

  <Card title="Webhook" description="폴링 대신 POST로 작업 상태 업데이트 받기." href="/ko/docs/references/webhook" />

  <Card title="제한 사항" description="동시 실행 한도, 폴링 권장 간격, API에서 아직 지원하지 않는 기능." href="/ko/docs/quick-start/limits" />

  <Card title="FAQ" description="이메일과 멤버십으로 키를 받는 방식의 차이, 점검 안내, API 생성물의 공개 범위." href="/ko/docs/faq" />

  <Card title="저작권과 라이선스" description="생성 이미지의 권리와 PixAI 모델의 상업적 이용 조건." href="/ko/docs/about/copyright" />
</Cards>

기계 판독용 버전 [#기계-판독용-버전]

* [/llms.txt](/llms.txt)는 이 문서의 모든 페이지를 한 줄 요약과 함께 나열하고, [/llms-full.txt](/llms-full.txt)는 모든 페이지를 하나의 Markdown 파일로 담고 있습니다.
* 페이지 URL 끝에 `.mdx`를 붙이면 해당 페이지를 Markdown으로 받을 수 있습니다. 예: [/ko/docs/quick-start/limits.mdx](/ko/docs/quick-start/limits.mdx)

도움이 필요하신가요? [#도움이-필요하신가요]

[api@withpixai.art](mailto:api@withpixai.art)로 메일을 보내시거나 [PixAI 공식 Discord](https://discord.com/invite/pixai&#x29;의 **#api-beta-test** 채널을 이용해 주세요. 자세한 내용은 [피드백](/ko/docs/about/feedback)을 참고하세요.


# 저작권 및 관련 권리



자세한 내용은 아래를 참고해 주세요.

* 라이선스: [Apache 2.0](http://www.apache.org/licenses/LICENSE-2.0.html)
* 서비스 약관: [pixai.art/terms](https://pixai.art/terms)

API를 통해 생성된 이미지의 저작권은 사용자에게 귀속됩니다. PixAI는 사용자 생성 작품에 대해 어떠한 저작권도 주장하지 않습니다. 단, 생성된 콘텐츠가 제3자의 권리를 침해하지 않으며, 적용 가능한 관련 법령을 준수해야 합니다.

PixAI 공식 모델(예: Haruka, Tsubaki)의 저작권은 PixAI에 귀속됩니다. 승인된 사용자에게는 해당 모델을 상업적 활동에 사용하는 권한이 부여되지만, 모델 파일 자체의 재판매 또는 재배포는 금지됩니다.


# 문의하기





베타 테스트 기간 중 문제나 제안 사항이 있다면 [api@withpixai.art](mailto:api@withpixai.art&#x29;로 이메일을 보내거나, 공식 Discord의 **#api-beta-test** 채널을 통해 의견을 남겨 주세요.

[<img alt="discord channel" src="__img0" />](https://discord.com/invite/pixai)


# 모델



추천 모델 [#추천-모델]

| 모델명        | 모델 버전 ID            | 장점                                  |
| ---------- | ------------------- | ----------------------------------- |
| Tsubaki.2  | 1983308862240288769 | 정교한 이해, 완벽한 인체, 다양한 스타일, 다중 캐릭터 최적화 |
| Haruka v2  | 1861558740588989558 | 품질이 안정적이고 디테일이 섬세하며 손 표현이 정확함       |
| Hoshino v2 | 1954632828118619567 | 일본에서 인기가 높은 스타일                     |

모델 목록 [#모델-목록]

Haruka v2 [#haruka-v2]

* 모델 유형: `SDXL`
* 모델 버전 ID: `1861558740588989558` (API의 modelId로 사용)
* 링크: [https://pixai.art/model/1861558737426484240-Haruka-v2](https://pixai.art/model/1861558737426484240-Haruka-v2)

**허용되는 샘플링 방법**

| Key             | Value                                                                                                                                           |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| samplingMethods | Euler a, Euler, LMS, Heun, DPM2 Karras, DPM2 a Karras, DDIM, DPM++ 2M Karras, DPM++ 2S a Karras, DPM++ SDE Karras, DPM++ 2M SDE Karras, Restart |

Tsubaki.2 [#tsubaki2]

* 모델 유형: `DIT`
* 모델 버전 ID: `1983308862240288769` (API의 modelId로 사용)
* 링크: [https://pixai.art/model/1982880136609467518-Tsubaki.2](https://pixai.art/model/1982880136609467518-Tsubaki.2)

**허용되는 샘플링 방법**

| Key             | Value                                                                                                                                           |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| samplingMethods | Euler a, Euler, LMS, Heun, DPM2 Karras, DPM2 a Karras, DDIM, DPM++ 2M Karras, DPM++ 2S a Karras, DPM++ SDE Karras, DPM++ 2M SDE Karras, Restart |

Hoshino v2 [#hoshino-v2]

* 모델 유형: `SDXL`
* 모델 버전 ID: `1954632828118619567` (API의 modelId로 사용)
* 링크: [https://pixai.art/model/1954632827019711809-Hoshino-v2](https://pixai.art/model/1954632827019711809-Hoshino-v2)

**허용되는 샘플링 방법**

| Key             | Value                                                                                                                                           |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| samplingMethods | Euler a, Euler, LMS, Heun, DPM2 Karras, DPM2 a Karras, DDIM, DPM++ 2M Karras, DPM++ 2S a Karras, DPM++ SDE Karras, DPM++ 2M SDE Karras, Restart |


# 지원 해상도



v2 API는 `aspectRatio` + `size` 조합으로 출력 해상도를 결정합니다. 모든 치수는 디퓨전 백엔드 요구 사항에 따라 16의 배수입니다.

| 종횡비  | 1k (너비 × 높이) | 1.5k (너비 × 높이) |
| ---- | ------------ | -------------- |
| 1:1  | 1024 × 1024  | 1536 × 1536    |
| 2:3  | 848 × 1280   | 1024 × 1536    |
| 3:2  | 1280 × 848   | 1536 × 1024    |
| 3:4  | 864 × 1152   | 1152 × 1536    |
| 4:3  | 1152 × 864   | 1536 × 1152    |
| 3:5  | 768 × 1280   | 912 × 1536     |
| 5:3  | 1280 × 768   | 1536 × 912     |
| 9:16 | 720 × 1280   | 864 × 1536     |
| 16:9 | 1280 × 720   | 1536 × 864     |
| 1:3  | 512 × 1536   | 512 × 1536     |
| 3:1  | 1536 × 512   | 1536 × 512     |

* 기본값: `aspectRatio: "1:1"`, `size: "1k"` → 1024 × 1024.
* `1.5k`의 최장변은 1536 px입니다. 극단적인 비율(1:3, 3:1)에서는 1k와 동일한 치수입니다.
* 모든 종횡비는 모든 모델 유형(SDXL, DiT, Tsubaki.2)에서 사용 가능합니다.


# Webhook



개발자는 웹훅을 설정하여 작업 상태에 대한 알림을 받을 수 있습니다.

작업이 시작, 완료, 취소 또는 실패하면 지정된 URL로 POST 요청이 전송됩니다.

[프로필 페이지](https://pixai.art/profile/edit/api)에서 설정할 수 있습니다.

REST API에서 `callbackUrl`을 사용하는 경우 본문 형식은 다음과 같습니다:

```json
{
    "action": "task_running",
    "data": {
        "id": "1829312678046282149",
        "status": "running",
        "createdAt": "2024-12-27T09:25:46.436Z",
        "updatedAt": "2024-12-27T09:26:01.912Z",
        "outputs": {
            "mediaIds": [],
            "mediaUrls": []
        }
    }
}
```


# PixAI API를 사용하려면?



방법 A (권장) [#방법-a-권장]

[api@withpixai.art](mailto:api@withpixai.art)로 연락해 아래 정보를 이메일에 포함해 주세요.

* 회사명: (회사/단체명)
* 직위: (회사 내 역할)
* 예상 사용량: (월 요청 수 등 API 사용량 추정)
* 사용 목적: (API 활용 계획에 대한 간단한 설명)

제출 후, 영업일 기준 5일 이내에 다음 절차를 안내드리기 위해 연락드립니다.

방법 B [#방법-b]

PixAI 공식 웹사이트 또는 [이 양식](https://docs.google.com/forms/d/1hJJYLOWhiq3HAH06kNEyiG1ISLDhiIh-8CqfndikN40/viewform?edit_requested=true)을 통해 베타 테스트 참여를 신청하세요.

심사 통과 시 API 접근 결과와 후속 안내가 포함된 이메일을 받게 됩니다.

문의, 피드백 또는 제안 사항이 있으시면 언제든지 [api@withpixai.art](mailto:api@withpixai.art)로 연락해 주세요.


# 첫 번째 API 호출





기본 URL: `https://api.pixai.art/v2`

인증: 모든 요청에 `Authorization: Bearer YOUR_API_KEY` 헤더를 추가하세요. API 키 발급 방법은 [PixAI API를 사용하려면?](/ko/docs/quick-start/enroll-in-api)을 참고하세요.

단계 [#단계]

<div className="fd-steps">
  <div className="fd-step">
    작업 제출 [#작업-제출-step]

    `POST /image/create`를 전송합니다. 필수 필드는 `modelVersionId`와 `prompt`입니다.

    ```bash
    curl -X POST https://api.pixai.art/v2/image/create \
      -H "Authorization: Bearer $PIXAI_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "modelVersionId": "1983308862240288769",
        "prompt": "1girl, green hair, masterpiece, best quality, solo, standing, flower",
        "aspectRatio": "9:16",
        "mode": "standard"
      }'
    ```

    응답:

    ```json
    {
      "id": "TASK_ID",
      "status": "waiting",
      "createdAt": "2026-03-04T04:32:10.635Z",
      "updatedAt": "2026-03-04T04:32:10.635Z",
      "outputs": {
        "mediaIds": [],
        "mediaUrls": []
      }
    }
    ```

    응답의 `id`를 기록해 두세요 — 다음 단계에서 사용하는 `TASK_ID`입니다.

    <Callout type="info">
      `modelVersionId`는 PixAI의 모델 버전 URL `https://pixai.art/model/<id>/<modelVersionId>`에서 마지막 세그먼트입니다. 추천 모델은 [모델](/ko/docs/references/models#recommended-models)을 참고하세요.
    </Callout>
  </div>

  <div className="fd-step">
    상태 폴링 [#상태-폴링-step]

    `status`가 완료 상태가 될 때까지 반복합니다.

    ```bash
    curl https://api.pixai.art/v1/task/TASK_ID \
      -H "Authorization: Bearer $PIXAI_API_KEY"
    ```

    | 상태          | 의미          |
    | :---------- | :---------- |
    | `waiting`   | 작업이 대기 중    |
    | `running`   | 생성 진행 중     |
    | `completed` | 완료, 결과물 준비됨 |
    | `failed`    | 생성 실패       |
    | `cancelled` | 작업이 취소됨     |

    `completed` 상태가 되면 `outputs.mediaUrls`에 이미지 URL이 포함됩니다.

    <Callout type="warn">
      폴링은 **1.5초**에 한 번을 초과하지 마세요. 재시도 시 지수 백오프를 사용하세요. 각 계정은 `waiting` 또는 `running` 상태의 작업을 동시에 최대 10개까지 허용합니다. 자세한 내용은 [제한 사항](/ko/docs/quick-start/limits)을 참고하세요.
    </Callout>
  </div>

  <div className="fd-step">
    이미지 다운로드 [#이미지-다운로드-step]

    ```bash
    curl -L "MEDIA_URL" -o output.png
    # 또는 미디어 ID로:
    curl -L https://api.pixai.art/v1/media/MEDIA_ID/image \
      -H "Authorization: Bearer $PIXAI_API_KEY" -o output.png
    ```

    <Callout type="warn">
      생성된 이미지는 **영구적으로 보관되지 않습니다** — 작업이 완료되는 즉시 다운로드하세요.
    </Callout>
  </div>
</div>

다음 단계 [#다음-단계]

* [모델](/ko/docs/references/models) — 사용 가능한 모델 확인
* [Webhook](/ko/docs/references/webhook) — 폴링 없이 작업 업데이트 수신


# 이 문서에 대하여



이 문서는 PixAI 플랫폼을 시작하는 데 도움을 드리기 위해 만들어졌습니다. PixAI API를 사용하여 AI의 강력한 기능을 활용한 이미지 생성 애플리케이션을 구축할 수 있습니다.



<Cards>
  <Card title="RESTful API" href="/ko/docs/api-v2/image/createImage" />

  <Card title="API 키 관리" href="https://pixai.art/profile/edit/api" />
</Cards>


# 제한 사항



요청 제한 [#요청-제한]

* 각 API 계정은 동시에 최대 10개의 작업만 처리할 수 있습니다(`pending` 또는 `running` 상태의 작업 합계 최대 10개).
* 현재 API 호출 자체에 대한 요청 속도 제한은 없습니다. 다만 합리적으로 사용해 주세요. 예를 들어 재시도 시 지수 백오프를 사용하고, 1.5초에 한 번을 초과하는 빈번한 폴링은 피하시기 바랍니다.

기능 제한 [#기능-제한]

* 현재 동영상 생성은 지원하지 않습니다.
* PixAI Reference Pro, PixAI Edit, PixAI Edit Lite는 아직 제공되지 않습니다(개발 중).


# ID로 미디어 조회



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/openapi-spec.ko.yaml&#x22;" operations="[{&#x22;path&#x22;:&#x22;/media/{mediaId}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# ID로 미디어 이미지 조회



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/openapi-spec.ko.yaml&#x22;" operations="[{&#x22;path&#x22;:&#x22;/media/{mediaId}/image&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# 이미지 또는 동영상 업로드



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/openapi-spec.ko.yaml&#x22;" operations="[{&#x22;path&#x22;:&#x22;/media/upload&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# 생성 작업 생성 요청



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/openapi-spec.ko.yaml&#x22;" operations="[{&#x22;path&#x22;:&#x22;/task&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


# ID로 작업 상세 조회



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/openapi-spec.ko.yaml&#x22;" operations="[{&#x22;path&#x22;:&#x22;/task/{taskId}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


# 이미지 생성 작업 생성



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;/openapi-spec.v2.ko.yaml&#x22;" operations="[{&#x22;path&#x22;:&#x22;/image/create&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />